Restful API MCP Server

MCP RESTful API服务器

用于RESTful API操作和JSON服务器的模型上下文协议服务器。该服务器充当大型语言模型和REST API之间的桥梁，使AI模型能够通过模型上下文协议与外部服务进行交互。

特性

• 完成CRUD操作：GET、POST、PUT、PATCH和DELETE HTTP方法
• JSON服务器兼容：与JSON服务器和其他RESTful API无缝协作
• 多种身份验证方法：基本身份验证、承载令牌或无身份验证
• 基于环境的配置：通过环境变量轻松设置
• 资源发现：将API端点显示为可发现的MCP资源
• 全面的错误处理：详细的错误消息和日志记录
• TypeScript：全类型安全和出色的开发人员体验
• 生产就绪：包括构建优化、linting和测试

快速开始

先决条件

• Node.js 20.0.0或更高版本
• 访问Restful-API
• 有效的Restful-API凭据

用法

基本MCP集成

{
  "mcpServers": {
    "restful-api-mcp-server": {
      "command": "npx",
      "args": ["-y", "restful-api-mcp-server"],
      "env": {
        "API_BASE_URL": "https://jsonplaceholder.typicode.com",
        "API_AUTH_TYPE": "none"
      }
    }
  }
}

安装

本地安装

# Clone the repository
git https://github.com/mikdanjey/restful-api-mcp-server.git
cd restful-api-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

快速开始

选项1：使用.env文件（推荐）

1. 运行安装脚本：

npm run setup

这将：

• 复制 .env.example 向 .env
• 安装依赖项
• 构建项目

1. 使用API配置编辑.env文件：

# Edit .env file
API_BASE_URL=https://jsonplaceholder.typicode.com
API_AUTH_TYPE=none

1. 启动服务器：

npm start

选项2：使用环境变量

1. 设置环境变量：

# For JSONPlaceholder API (no authentication)
export API_BASE_URL="https://jsonplaceholder.typicode.com"
export API_AUTH_TYPE="none"

# For APIs with Bearer token authentication
export API_BASE_URL="https://api.example.com"
export API_AUTH_TYPE="token"
export API_AUTH_TOKEN="your-bearer-token-here"

# For APIs with Basic authentication
export API_BASE_URL="https://api.example.com"
export API_AUTH_TYPE="basic"
export API_BASIC_AUTH_USERNAME="your-username"
export API_BASIC_AUTH_PASSWORD="your-password"

1. 启动服务器：

# If installed globally
restful-api-mcp-server

# If running from source
npm start

# With debug logging
restful-api-mcp-server --debug

配置

服务器可以使用环境变量或 .env 文件。这 .env 建议使用文件方法进行开发。

使用.env文件

1. 复制示例文件： cp .env.example .env
2. 编辑 .env 根据您的配置
3. 服务器将在启动时自动加载这些变量

环境变量

命令行选项

restful-api-mcp-server [options]

Options:
  -h, --help     Show help message
  -v, --version  Show version information
  -d, --debug    Enable debug logging
  -c, --config   Specify config file path (future use)

MCP工具

服务器提供以下MCP工具用于与REST API交互：

api_get

执行GET请求以检索数据。

参数：

• path （字符串，必需）：API端点路径（例如，“/users/1”）
• queryParams （object，可选）：将参数作为键值对进行查询
• headers （对象，可选）：其他HTTP标头

例子：

{
  "name": "api_get",
  "arguments": {
    "path": "/users",
    "queryParams": {
      "page": "1",
      "limit": "10"
    },
    "headers": {
      "Accept": "application/json"
    }
  }
}

api_post

通过POST请求创建新资源。

参数：

• path （字符串，必需）：API终结点路径
• body （object，可选）：请求正文数据
• headers （对象，可选）：其他HTTP标头

api_put

通过PUT请求更新资源（完全替换）。

参数：

• path （字符串，必需）：API终结点路径
• body （object，可选）：请求正文数据
• headers （对象，可选）：其他HTTP标头

api_patch

通过PATCH请求部分更新资源。

参数：

• path （字符串，必需）：API终结点路径
• body （object，可选）：请求正文数据
• headers （对象，可选）：其他HTTP标头

api_delete

通过Delete请求删除资源。

参数：

• path （字符串，必需）：API终结点路径
• headers （对象，可选）：其他HTTP标头

MCP资源

服务器将API端点公开为可发现的MCP资源：

• 资源uri: api://endpoints/{endpoint}
• 描述：提供有关可用API终结点及其支持的操作的文档

发展

先决条件

• Node.js 20.0.0或更高版本
• npm或yarn包管理器

设置

# Clone the repository
git clone https://github.com/mikdanjey/restful-api-mcp-server.git
cd restful-api-mcp-server

# Run the setup script (installs dependencies, creates .env, and builds)
npm run setup

# Or do it manually:
# npm install
# cp .env.example .env
# Edit .env with your configuration
# npm run build

可用脚本

# Setup
npm run setup           # Complete setup: create .env, install deps, build
npm run setup:env       # Create .env file from .env.example
npm run validate        # Validate configuration before starting

# Development
npm run dev             # Build and watch for changes
npm run build:dev       # Build for development
npm run start:dev       # Build and start in one command
npm run type-check      # Run TypeScript type checking

# Production
npm run build           # Full production build with linting and type checking
npm run build:prod      # Optimized production build
npm start              # Start the built server

# Testing
npm test               # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Run tests with coverage report

# Code Quality
npm run lint           # Run ESLint
npm run lint:fix       # Run ESLint with auto-fix
npm run clean          # Clean build artifacts

# Alternative: Using Make
make setup             # Same as npm run setup
make build             # Same as npm run build
make start             # Same as npm start
make dev               # Same as npm run dev
make test              # Same as npm test
make lint              # Same as npm run lint

项目结构

src/
├── auth/           # Authentication strategies
├── client/         # HTTP client wrapper
├── config/         # Configuration management
├── resources/      # MCP resource providers
├── tools/          # MCP tool handlers
├── types/          # TypeScript type definitions
└── index.ts        # Main entry point

tests/
├── unit/           # Unit tests
├── integration/    # Integration tests
└── fixtures/       # Test fixtures and mocks

例子

与JSON占位符API一起使用

# Set up environment
export API_BASE_URL="https://jsonplaceholder.typicode.com"
export API_AUTH_TYPE="none"

# Start the server
restful-api-mcp-server

# The server will provide tools to interact with JSONPlaceholder:
# - GET /posts, /users, /comments, etc.
# - POST /posts (creates mock resources)
# - PUT /posts/1 (updates mock resources)
# - DELETE /posts/1 (deletes mock resources)

使用JSON服务器

# Start a local JSON Server (install with: npm install -g json-server)
echo '{"posts": [{"id": 1, "title": "Hello World"}], "users": [{"id": 1, "name": "John"}]}' > db.json
json-server --watch db.json --port 3000

# Set up environment for local JSON Server
export API_BASE_URL="http://localhost:3000"
export API_AUTH_TYPE="none"

# Start the MCP server
restful-api-mcp-server

# The server will provide tools to interact with JSON Server:
# - GET /posts, /users (retrieve data)
# - POST /posts (create new posts)
# - PUT /posts/1 (update posts)
# - DELETE /posts/1 (delete posts)

与GitHub API一起使用

# Set up environment
export API_BASE_URL="https://api.github.com"
export API_AUTH_TYPE="token"
export API_AUTH_TOKEN="ghp_your_github_token_here"

# Start the server
restful-api-mcp-server

# The server will provide tools to interact with GitHub API:
# - GET /user (get authenticated user)
# - GET /repos/owner/repo (get repository info)
# - POST /repos/owner/repo/issues (create issues)

错误处理

服务器提供全面的错误处理：

• 配置错误：清除缺少或无效环境变量的消息
• 身份验证错误：身份验证失败的详细反馈
• 网络错误：超时和连接错误处理
• HTTP错误：正确处理4xx和5xx状态代码
• 验证错误：输入验证，并显示有用的错误消息

所有错误都以一致的格式返回，并包含适当的错误代码和详细信息。

故障排除

配置问题

如果您在配置方面遇到问题：

1. 验证您的配置：

   npm run validate

1. 检查.env文件：

   cat .env

1. 验证是否设置了所需的环境变量：

- API_BASE_URL -必须是有效的URL - API_AUTH_TYPE -必须是“基本”、“令牌”或“无” - 对于令牌身份验证： API_AUTH_TOKEN 必须设置 - 对于基本身份验证： API_BASIC_AUTH_USERNAME 和 API_BASIC_AUTH_PASSWORD 必须设置

常见问题

• “配置验证失败”：检查所有必需的环境变量是否设置正确
• “无法访问API基础URL”：验证URL是否正确以及API是否正在运行
• 身份验证错误：验证API的凭据是否正确
• 构建错误：确保你有Node.js 18+并运行 npm install

调试模式

启用调试日志记录以获取更详细的信息：

# Using .env file
echo "DEBUG=true" >> .env

# Using environment variable
DEBUG=true npm start

# Using command line flag
npm start -- --debug

日志记录

服务器包括结构化日志记录：

• 信息级别：服务器启动、配置和操作状态
• 警告级别：非关键问题和警告
• 错误级别：完整上下文中的错误和异常
• 调试级别：详细的调试信息（通过启用 --debug 或 DEBUG=true)

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 为您的更改添加测试
5. 运行测试套件(npm test)
6. 跑linting(npm run lint)
7. 提交您的更改(git commit -m 'Add amazing feature')
8. 推到分支(git push origin feature/amazing-feature)
9. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• 问题：报告错误并请求功能
• 文档：完整文档可在 文档 目录
• 例子：更多示例请参见 示例 目录