# API Docs MCP Server

A Model Context Protocol (MCP) server that provides tools to explore and query API definitions from OpenAPI/Swagger JSON files.

## Overview

This MCP server reads API definition files from the directory `D:\My works\DauTuCong\Frontend\src\assets\api-definitions` and provides various tools to search, explore, and retrieve information about the APIs defined in those files.

## Features

- **List all APIs**: Get an overview of all available API definitions
- **Search by tag**: Find endpoints grouped by functional tags
- **Search by path**: Find endpoints using path pattern matching (supports regex)
- **Get endpoint details**: Retrieve complete information about specific endpoints including parameters, request bodies, and responses
- **Get schema details**: Explore data models and schemas defined in the API specifications
- **List schemas**: View all available schemas in a specific API definition

## Installation

1. Install dependencies:
```bash
npm install
```

## MCP Setup for AI Agents

This MCP server can be used with various AI coding assistants and agents. Below are setup instructions for common platforms.

### Claude Code (Claude Desktop)

1. Open Claude Desktop settings
2. Navigate to the MCP servers configuration
3. Add the following configuration:

```json
{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}
```

4. Save the configuration and restart Claude Desktop
5. The MCP server tools will now be available in Claude Code

### Cline (VS Code Extension)

1. Install the Cline extension from the VS Code Marketplace
2. Open VS Code settings (Ctrl/Cmd + ,)
3. Search for "Cline: MCP Servers"
4. Add the MCP server configuration:

```json
{
  "cline.mcpServers": [
    {
      "name": "api-docs",
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  ]
}
```

5. Save the settings and reload VS Code
6. The MCP tools will be available in Cline

### Kilo Code

1. Open Kilo Code settings
2. Navigate to MCP servers configuration
3. Add the server configuration:

```json
{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}
```

4. Save and restart Kilo Code
5. The MCP server will be automatically connected

### Windsurf (Codeium)

1. Open Windsurf settings
2. Navigate to Extensions → MCP
3. Add a new MCP server with the following configuration:

- **Name**: api-docs
- **Command**: node
- **Arguments**: d:/My works/api-docs-mcp/index.js
- **Environment Variables**:
  - API_DEFINITIONS_DIR = D:/My works/DauTuCong/Frontend/src/assets/api-definitions

4. Save the configuration
5. Restart Windsurf to activate the MCP server

### Cursor

1. Open Cursor settings (Ctrl/Cmd + ,)
2. Navigate to the MCP servers section
3. Add the following configuration:

```json
{
  "cursor.mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}
```

4. Save the settings
5. Reload Cursor to apply the changes

### General MCP Configuration Notes

- **Path Adjustments**: Update the file paths in the configurations above to match your actual project location
- **Environment Variable**: The `API_DEFINITIONS_DIR` environment variable should point to your API definitions directory
- **Permissions**: Ensure the AI agent has permission to execute the MCP server
- **Troubleshooting**: If the MCP server doesn't connect, check:
  - Node.js is installed and accessible
  - The file paths are correct
  - The API definitions directory exists and contains valid JSON files
  - Check the agent's logs for connection errors

### Verifying MCP Connection

After setting up the MCP server with any AI agent, you can verify the connection by:

1. Asking the AI agent to list available tools
2. Requesting to list all APIs using the `list_apis` tool
3. Checking if the agent can access API definitions and schemas

If successful, the AI agent should be able to query API definitions, search endpoints, and retrieve schema information using the MCP tools.

## Usage

### Running the Server

Start the MCP server:
```bash
npm start
```

The server runs on stdio and can be connected to by any MCP-compatible client.

### Available Tools

#### 1. `list_apis`
List all available API definitions with their titles and versions.

**Parameters:** None

**Example Response:**
```json
[
  {
    "name": "auth",
    "title": "Authentication API",
    "version": "v1",
    "filename": "auth.swagger.json"
  }
]
```

#### 2. `get_api_details`
Get detailed information about a specific API definition.

**Parameters:**
- `name` (required): API name (e.g., "auth", "projects", "users")

**Example:**
```json
{
  "name": "auth"
}
```

#### 3. `list_tags`
List all tags across all API definitions.

**Parameters:** None

**Example Response:**
```json
["Auth", "Projects", "Users"]
```

#### 4. `search_by_tag`
Search for endpoints by tag name.

**Parameters:**
- `tag` (required): Tag name to search for

**Example:**
```json
{
  "tag": "Auth"
}
```

#### 5. `search_by_path`
Search for endpoints by path pattern (supports regex).

**Parameters:**
- `pattern` (required): Path pattern to search for (e.g., "/api/Auth", "/api/.*")

**Example:**
```json
{
  "pattern": "/api/Auth"
}
```

#### 6. `get_endpoint`
Get detailed information about a specific endpoint.

**Parameters:**
- `api` (required): API name (e.g., "auth", "projects")
- `path` (required): Endpoint path (e.g., "/api/Auth/login")
- `method` (required): HTTP method (GET, POST, PUT, DELETE, etc.)

**Example:**
```json
{
  "api": "auth",
  "path": "/api/Auth/login",
  "method": "POST"
}
```

#### 7. `get_schema`
Get detailed information about a specific schema.

**Parameters:**
- `api` (required): API name (e.g., "auth", "projects")
- `schemaName` (required): Schema name (e.g., "LoginCommand", "AuthResponseDto")

**Example:**
```json
{
  "api": "auth",
  "schemaName": "LoginCommand"
}
```

#### 8. `list_schemas`
List all schemas in a specific API definition.

**Parameters:**
- `api` (required): API name (e.g., "auth", "projects")

**Example:**
```json
{
  "api": "auth"
}
```

## Configuration

The API definitions directory can be configured via environment variable:

```bash
export API_DEFINITIONS_DIR="path/to/your/api-definitions"
npm start
```

Or set it inline:

```bash
API_DEFINITIONS_DIR="path/to/your/api-definitions" npm start
```

If not set, it defaults to `D:\My works\DauTuCong\Frontend\src\assets\api-definitions`.

## API Definitions Structure

The MCP server expects OpenAPI/Swagger JSON files in the configured directory. Each file should follow the OpenAPI 3.0 specification format.

### Directory Structure Example

```
api-definitions/
├── auth.swagger.json
├── projects.swagger.json
├── users.swagger.json
└── ...
```

### Sample API Definition File Structure

Each API definition file should contain the following structure:

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Authentication API",
    "version": "v1",
    "description": "API for authentication operations"
  },
  "tags": [
    {
      "name": "Auth",
      "description": "Authentication endpoints"
    }
  ],
  "paths": {
    "/api/Auth/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "User login",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginCommand"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful login",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponseDto"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LoginCommand": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        },
        "required": ["username", "password"]
      },
      "AuthResponseDto": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserDto"
          }
        }
      },
      "UserDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### Key Components

1. **Info Section**: Contains API metadata (title, version, description)
2. **Tags**: Categorize endpoints for better organization
3. **Paths**: Define all API endpoints with their HTTP methods
4. **Components/Schemas**: Define reusable data models and request/response structures

### File Naming Convention

- Use descriptive names: `auth.swagger.json`, `projects.swagger.json`
- Keep names lowercase and use hyphens for multi-word names
- The filename is used as the API identifier (without the `.swagger.json` extension)

### Supported Features

The MCP server supports:
- Multiple HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
- Path parameters (e.g., `/api/users/{id}`)
- Query parameters
- Request bodies with schema references
- Response schemas
- Multiple response status codes
- Tag-based endpoint categorization

## Example Workflows

### Find all authentication endpoints
1. Use `list_tags` to see available tags
2. Use `search_by_tag` with tag "Auth" to find all authentication endpoints
3. Use `get_endpoint` to get detailed information about specific endpoints

### Explore a specific API
1. Use `list_apis` to see all available APIs
2. Use `get_api_details` to get an overview of a specific API
3. Use `list_schemas` to see all data models in that API
4. Use `get_schema` to get detailed information about specific schemas

### Search for endpoints by path
1. Use `search_by_path` with pattern "/api/Auth" to find all auth-related endpoints
2. Use `search_by_path` with pattern "/api/.*" to find all endpoints
3. Use `get_endpoint` to get detailed information about specific endpoints

## Error Handling

The server returns error messages in the following cases:
- API definition not found
- Endpoint not found
- Schema not found
- Invalid file format
- File read errors

All errors are returned with an `isError: true` flag in the response.

## License

MIT