MCP Service

MCP平台服务

用于与外部平台集成的最小模型上下文协议（MCP）服务。此服务提供CRUD操作、参考数据获取和身份验证功能。

特性

• ✅ 实体的CRUD操作（创建、读取、更新、删除）
• ✅ 参考数据获取（状态、优先级、类别等）
• ✅ 通过API令牌（环境变量）或登录工具进行身份验证
• ✅ 令牌刷新支持
• ✅ MCP兼容服务器实现
• ✅ 准备通过运行 npx 来自GitHub

先决条件

• Node.js 18.0.0或更高版本
• npm或纱线

安装

选项1：通过npx运行（来自GitHub）

npx github:Artemida1609/mcp-service

选项2：本地安装

git clone https://github.com/Artemida1609/mcp-service.git
cd mcp-service
npm install

环境变量

该服务支持以下环境变量：

\* API_TOKEN 除非您使用 login 验证工具。

用法

设置环境变量

Linux/macOS：

export API_TOKEN="your-api-token-here"
export API_BASE_URL="https://api.yourplatform.com/v1"

Windows（PowerShell）：

$env:API_TOKEN="your-api-token-here"
$env:API_BASE_URL="https://api.yourplatform.com/v1"

Windows（CMD）：

set API_TOKEN=your-api-token-here
set API_BASE_URL=https://api.yourplatform.com/v1

运行服务

通过npx：

npx github:your-username/mcp-service

当地：

npm start
# or
node index.js

该服务在stdio上作为MCP服务器运行，并通过模型上下文协议进行通信。

MCP服务器集成

Claude桌面配置

将此添加到您的Claude Desktop配置文件中(claude_desktop_config.json):

macOS：

{
  "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"
      }
    }
  }
}

窗户：

{
  "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)

例子：

{
  "entityId": "123",
  "entityType": "project"
}

create_entity

在平台中创建一个新实体。

参数：

• entityType （string，必填）：要创建的实体类型
• data （object，必填）：实体数据

例子：

{
  "entityType": "task",
  "data": {
    "title": "New Task",
    "description": "Task description",
    "status": "open"
  }
}

update_entity

更新现有实体。

参数：

• entityId （string，必填）：唯一标识符
• entityType （字符串，必填）：实体类型
• data （对象，必填）：要更新的字段

例子：

{
  "entityId": "123",
  "entityType": "task",
  "data": {
    "status": "completed"
  }
}

delete_entity

从平台中删除实体。

参数：

• entityId （string，必填）：唯一标识符
• entityType （字符串，必填）：实体类型

例子：

{
  "entityId": "123",
  "entityType": "task"
}

参考数据

get_reference

获取参考数据（状态、优先级、类别等）。

参数：

• referenceType （字符串，必填）：引用类型(statuses, priorities, categories, tags, users)
• filters （对象，可选）：可选过滤器

例子：

{
  "referenceType": "statuses",
  "filters": {
    "active": true
  }
}

认证

login

使用用户名和密码进行身份验证。为后续请求存储令牌。

参数：

• username （字符串，必填）：用户名
• password （字符串，必填）：密码

例子：

{
  "username": "user@example.com",
  "password": "password123"
}

refresh_token

刷新过期的访问令牌。

参数：

• refreshToken （string，必填）：刷新令牌

例子：

{
  "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. 克隆存储库
2. 安装依赖项： npm install
3. 设置环境变量
4. 运行： npm start

测试

要手动测试服务，您可以使用MCP客户端或直接测试处理程序：

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或更高版本

定制

要使此服务适应您的特定平台：

1. 更新 API_BASE_URL 到您平台的API端点
2. 修改中的端点路径 handlers.js 如果您的API使用不同的路由
3. 调整实体类型 schemas.js 匹配您平台的实体
4. 更新中的引用类型 get_reference 处理器
5. 修改中的身份验证流程 handleLogin 如果您的平台使用不同的身份验证机制

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

支持

有关问题和疑问，请在GitHub上打开问题。