yapi-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server for YApi that enables AI tools like Claude Desktop and Cursor to interact with YApi API management platform. The server supports dual authentication methods and provides comprehensive API management capabilities.

Core Commands

Development

# Install dependencies
npm install

# Development with file watching
npm run dev

# Build the project
npm run build

# Start the server
npm start

# Clean build artifacts
npm run clean

Testing

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Test coverage report
npm run test:coverage

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

Code Quality

# Lint TypeScript code
npm run lint

# Fix linting issues automatically
npm run lint:fix

Authentication Testing

# Test user authentication
YAPI_BASE_URL=http://localhost:40001 [email protected] YAPI_PASSWORD=password npx tsx tests/auth-test.ts

# Test authentication priority (token vs user)
npx tsx tests/auth-priority-test.ts

Architecture

Core Components

YApiMcpServer (src/server.ts)

• Main MCP server implementation using @modelcontextprotocol/sdk
• Handles tool registration and request routing
• Integrates with YApiClient for API operations

YApiClient (src/services/yapi-client.ts)

• HTTP client for YApi API interactions using axios
• Implements dual authentication system with priority logic:
  1. Priority 1: Project token authentication (YAPI_PROJECT_TOKEN)
  2. Priority 2: User authentication (YAPI_USERNAME + YAPI_PASSWORD)
• Features smart caching, session management, and 401 retry logic

Configuration System (src/config.ts)

• Environment-based configuration loading
• Validates authentication requirements (either token OR username+password)
• Supports flexible configuration options