MCP平台服务
用于与外部平台集成的最小模型上下文协议(MCP)服务。此服务提供CRUD操作、参考数据获取和身份验证功能。
特性
- ✅ 实体的CRUD操作(创建、读取、更新、删除)
- ✅ 参考数据获取(状态、优先级、类别等)
- ✅ 通过API令牌(环境变量)或登录工具进行身份验证
- ✅ 令牌刷新支持
- ✅ MCP兼容服务器实现
- ✅ 准备通过运行
npx来自GitHub
先决条件
- Node.js 18.0.0或更高版本
- npm或纱线
安装
选项1:通过npx运行(来自GitHub)```bash
npx github:Artemida1609/mcp-service
### 选项2:本地安装```bash
git clone https://github.com/Artemida1609/mcp-service.git
cd mcp-service
npm install
环境变量
该服务支持以下环境变量:
| 变量 | 描述 | 必填 | 默认 |
|---|---|---|---|
API_TOKEN |
用于身份验证的API令牌 | 否* | - |
API_BASE_URL |
外部平台API的基本URL | 否 | https://api.example.com/v1 |
API_TIMEOUT |
请求超时(毫秒) | 否 | 30000 |
ALLOW_LOGIN |
启用登录工具(true/false) | 否 | true |
* API_TOKEN 除非您使用 login 验证工具。
用法
设置环境变量
Linux/macOS:```bash
export API_TOKEN="your-api-token-here"
export API_BASE_URL="https://api.yourplatform.com/v1"
**Windows(PowerShell):**```powershell
$env:API_TOKEN="your-api-token-here"
$env:API_BASE_URL="https://api.yourplatform.com/v1"
Windows(CMD):```cmd
set API_TOKEN=your-api-token-here
set API_BASE_URL=https://api.yourplatform.com/v1
### 运行服务
**通过npx:**```bash
npx github:your-username/mcp-service
当地:```bash
npm start
or
node index.js
该服务在stdio上作为MCP服务器运行,并通过模型上下文协议进行通信。
## MCP服务器集成
### Claude桌面配置
将此添加到您的Claude Desktop配置文件中(`claude_desktop_config.json`):
**macOS:**```json
{
"mcpServers": {
"platform-service": {
"command": "npx",
"args": ["github:Artemida1609/mcp-service"],
"env": {
"API_TOKEN": "your-api-token-here",
"API_BASE_URL": "https://api.yourplatform.com/v1"
}
}
}
}
窗户:```json
{
"mcpServers": {
"platform-service": {
"command": "npx.cmd",
"args": ["github:Artemida1609/mcp-service"],
"env": {
"API_TOKEN": "your-api-token-here",
"API_BASE_URL": "https://api.yourplatform.com/v1"
}
}
}
}
### 其他MCP客户端
该服务使用MCP协议通过stdio进行通信。将MCP客户端配置为:
- 命令: `npx` (或 `npx.cmd` 在Windows上)
- Args: `["github:Artemida1609/mcp-service"]`
- 根据需要设置环境变量
## 可用工具
### CRUD操作
#### `get_entity`
按ID和类型检索特定实体。
**参数:**
- `entityId` (string,必填):实体的唯一标识符
- `entityType` (字符串,必填):实体类型(`user`, `project`, `task`, `document`)
**例子:**```json
{
"entityId": "123",
"entityType": "project"
}
create_entity
在平台中创建一个新实体。
参数:
entityType(string,必填):要创建的实体类型data(object,必填):实体数据
例子:```json
{
"entityType": "task",
"data": {
"title": "New Task",
"description": "Task description",
"status": "open"
}
}
#### `update_entity`
更新现有实体。
**参数:**
- `entityId` (string,必填):唯一标识符
- `entityType` (字符串,必填):实体类型
- `data` (对象,必填):要更新的字段
**例子:**```json
{
"entityId": "123",
"entityType": "task",
"data": {
"status": "completed"
}
}
delete_entity
从平台中删除实体。
参数:
entityId(string,必填):唯一标识符entityType(字符串,必填):实体类型
例子:```json
{
"entityId": "123",
"entityType": "task"
}
### 参考数据
#### `get_reference`
获取参考数据(状态、优先级、类别等)。
**参数:**
- `referenceType` (字符串,必填):引用类型(`statuses`, `priorities`, `categories`, `tags`, `users`)
- `filters` (对象,可选):可选过滤器
**例子:**```json
{
"referenceType": "statuses",
"filters": {
"active": true
}
}
认证
login
使用用户名和密码进行身份验证。为后续请求存储令牌。
参数:
username(字符串,必填):用户名password(字符串,必填):密码
例子:```json
{
"username": "user@example.com",
"password": "password123"
}
#### `refresh_token`
刷新过期的访问令牌。
**参数:**
- `refreshToken` (string,必填):刷新令牌
**例子:**```json
{
"refreshToken": "your-refresh-token-here"
}
API终点
该服务希望外部平台API遵循以下约定:
GET /entities/{entityType}/{entityId}-获取实体POST /entities/{entityType}-创建实体PUT /entities/{entityType}/{entityId}-更新实体DELETE /entities/{entityType}/{entityId}-删除实体GET /reference/{referenceType}-获取参考数据POST /auth/login-登录POST /auth/refresh-刷新令牌
所有请求都需要在 Authorization 头球
项目结构```
mcp-service/
├── index.js # Main MCP server entry point
├── config.js # Configuration and environment variables
├── auth.js # Authentication token management
├── api-client.js # HTTP client for API requests
├── handlers.js # Tool handler implementations
├── tools.js # Tool definitions and descriptions
├── schemas.js # Input schemas for tools
├── package.json # Dependencies and metadata
├── .gitignore # Git ignore rules
└── README.md # This file
## 发展
### 地方发展
1. 克隆存储库
1. 安装依赖项: `npm install`
1. 设置环境变量
1. 运行: `npm start`
### 测试
要手动测试服务,您可以使用MCP客户端或直接测试处理程序:```javascript
import { handleGetEntity } from './handlers.js';
const result = await handleGetEntity({
entityId: '123',
entityType: 'project'
});
console.log(result);
故障排除
“没有可用的身份验证令牌”错误
- 确保
API_TOKEN在您的环境中设置,或 - 使用
login首先进行身份验证的工具
“请求超时”错误
- 增加
API_TIMEOUT环境变量 - 检查网络连接
- 验证
API_BASE_URL是正确的
登录工具已禁用
- 集
ALLOW_LOGIN=true在环境变量中
未找到模块错误
- 跑
npm install安装依赖项 - 确保Node.js版本为18.0.0或更高版本
定制
要使此服务适应您的特定平台:
- 更新
API_BASE_URL到您平台的API端点 - 修改中的端点路径
handlers.js如果您的API使用不同的路由 - 调整实体类型
schemas.js匹配您平台的实体 - 更新中的引用类型
get_reference处理器 - 修改中的身份验证流程
handleLogin如果您的平台使用不同的身份验证机制
许可证
麻省理工学院
贡献
欢迎投稿!请随时提交拉取请求。
支持
有关问题和疑问,请在GitHub上打开问题。
