Content
# WebAPI MCP Server
A server that transforms traditional Web APIs into MCP tools, supporting batch registration of API interfaces and setting default request headers through the MCP tool.
Advantages:
1. Simpler than the traditional RAG model, easier to deploy, and allows direct integration between traditional business systems and large models without the need to develop additional interfaces, reducing redundant code and workload.
2. Supports batch import of JSON files, Markdown files, or file directories.
3. Compared to RAG's data slicing through vector databases, retrieving data directly via model calls can be more accurate and reliable.
4. Data security is enhanced by setting request header parameters in the converted MCP tool for more precise data permission management and control.
Original link: https://blog.csdn.net/qq_39336120/article/details/147537618
## Features
- **API Conversion** - Automatically converts any Web API into an MCP tool.
- **Dynamic Registration** - Dynamically register and remove APIs at runtime.
- **Global Request Headers** - Centrally manage default request headers for all APIs.
- **Flexible Parameters** - Supports various parameter types and validations.
- **Result Path** - Supports extracting specific data from nested responses.
- **Batch Loading** - Supports batch loading of API definitions from files or directories.
## Introducing Cursor or Other MCP Clients
```bash
{
"mcpServers": {
"webapi-mcp-server": {
"command": "npx",
"args": [
"-y",
"@yinzhouzhi/webapi-mcp-server",
"start"
]
}
}
}
```
## Installation
```bash
# Clone the project
git clone <repository-url>
cd webapi-mcp-server
# Install dependencies
npm install
# Initialize project directory
npm run setup
```
## Usage
### Start the Server
```bash
npm start
# Start with custom configuration
npm start -- --config path/to/config.json --apis-dir path/to/apis
# Start with environment variables
WEBAPI_CONFIG_FILE=path/to/config.json WEBAPI_APIS_DIR=path/to/apis WEBAPI_DEBUG=true npm start
```
### Configuration File Options
The configuration file supports JSON, YAML, and YML formats and can include the following options:
```json
{
"apiDirectories": [ // List of directories containing API definition files
"./apis",
"./more-apis"
],
"apiFiles": [ // List of paths for individual API definition files
"./specific-api.json",
"./another-api.md"
],
"globalHeaders": { // Default request headers applied to all API requests
"User-Agent": "WebAPI MCP Client/1.0", // User agent
"Accept": "application/json", // Accepted content type
"Authorization": "Bearer YOUR_TOKEN" // Authorization token
},
"debug": true // Whether to enable debug mode
}
```
| Configuration Item | Type | Description |
|--------------------|------|-------------|
| `apiDirectories` | Array | List of directories containing API definition files |
| `apiFiles` | Array | List of paths for individual API definition files |
| `globalHeaders` | Object | Default request headers applied to all API requests |
| `debug` | Boolean | Whether to enable debug mode |
### Running Example
```bash
npm run run-example
```
### Using the CLI Tool
```bash
# Start the server
npm run start
# Show example
npm run example
```
### Environment Variable Configuration
The server can also be configured through environment variables:
| Environment Variable | Description |
|----------------------|-------------|
| `WEBAPI_CONFIG_FILE` | Path to the configuration file |
| `WEBAPI_APIS_DIR` | Path to the API definition directory |
| `WEBAPI_DEBUG` | Enable debug mode (set to 'true') |
## MCP Tools
The server includes the following MCP tools:
| Tool Name | Description |
|-------------------------|-------------|
| `register_web_api` | Registers a Web API as an MCP tool, allowing it to be called directly via the MCP protocol. |
| `set_default_headers` | Sets global default request headers applicable to all API requests. |
| `list_registered_apis` | Lists all currently registered Web APIs and their configurations. |
| `unregister_api` | Removes a registered Web API tool. |
| `load_api_from_file` | Loads API definitions from a specified file and registers them as MCP tools. |
| `load_apis_from_directory` | Loads all API definition files from a specified directory and registers them as MCP tools. |
| `load_from_config` | Loads API definitions and settings from a configuration file. |
## API Definition Format
APIs can be defined using JSON or Markdown formats:
### JSON Format
```json
{
"name": "weather",
"description": "Get current weather information",
"url": "https://api.example.com/weather",
"method": "GET",
"parameters": {
"city": {
"type": "string",
"required": true, // Whether required
"description": "City name"
},
"units": {
"type": "string",
"required": false,
"description": "Temperature unit (celsius, fahrenheit)"
}
},
"headers": {
"X-API-Key": "your-api-key"
},
"resultPath": "data.current"
}
```
#### JSON Format Field Description
| Field | Type | Required | Description |
|---------------|----------|----------|-------------|
| `name` | String | Yes | Unique name of the API tool for MCP calls |
| `description` | String | Yes | Brief description of the API functionality |
| `url` | String | Yes | Full URL of the API, supports parameterized URL templates |
| `method` | String | Yes | HTTP request method (GET, POST, PUT, DELETE, etc.) |
| `parameters` | Object | No | API parameter definitions, each parameter includes type, required, and description attributes |
| `headers` | Object | No | Request headers specific to this API (will be merged with global headers) |
| `resultPath` | String | No | Path to extract results from the response, using dot notation (e.g., "data.items") |
| `bodyTemplate`| Object/String | No | Request body template for POST/PUT requests |
| `responseType`| String | No | Expected response type (json, text, blob, etc.) |
| `transform` | String | No | JavaScript code string for transforming the response |
### Markdown Format
```markdown
# Weather API
Get current weather information
## URL
https://api.example.com/weather
## Method
GET
## Parameters
- city (string, required): City name
- units (string, optional): Temperature unit (celsius, fahrenheit)
## Request Headers
- X-API-Key: your-api-key
## Result Path
data.current
```
#### Markdown Format Specification
The API definition in Markdown format must follow this structure:
1. **Level 1 Header (#)**: The name of the API, used as the MCP tool name.
2. **Description**: The text below the title serves as the API description.
3. **URL Section**: Starts with `## URL`, followed by the full URL of the API.
4. **Method Section**: Starts with `## Method`, followed by the HTTP method (GET, POST, etc.).
5. **Parameters Section (optional)**: Starts with `## Parameters`, each parameter is formatted as a list item.
- Format: `Parameter Name (Type, required/optional): Description`
6. **Request Headers Section (optional)**: Starts with `## Request Headers`, each request header is formatted as a list item.
- Format: `Header Name: Value`
7. **Result Path Section (optional)**: Starts with `## Result Path`, followed by the path to extract results.
8. **Request Body Template (optional)**: Starts with `## Request Body`, followed by a JSON format request body template.
9. **Response Type (optional)**: Starts with `## Response Type`, specifying the expected response type.
10. **Transform Function (optional)**: Starts with `## Transform Function`, containing JavaScript transformation code.
## Detailed Documentation
- [Convert Web API to MCP Tool](./docs/web-api-conversion.md) - How to use MCP tools to register and manage APIs.
## Example
See [API Example](./examples/api-example.js) to learn how to:
1. Set global default request headers
2. Register Web APIs
3. List registered APIs
4. Call registered APIs
5. Remove APIs
## Exported APIs
```javascript
const webapi = require('webapi-mcp-server');
// Create a custom server
const server = webapi.createServer({
debug: true,
configFile: './config.json',
apisDir: './apis'
});
// Use other exported functions
webapi.registerApi(apiDefinition);
webapi.unregisterApi('apiName');
webapi.getRegisteredApis();
webapi.loadApiFile('./path/to/api.json');
webapi.loadApisFromDirectory('./apis');
```
## License
MIT
