Utcp Docs Server

UTCP文档MCP服务器

一个全面的MCP服务器，帮助AI编码代理理解和实现通用工具调用协议（UTCP）

  

🚀 特性

• 🤖 LLM授权专家代理：用自然语言向具有深厚UTCP知识的OpenAI代理提问
• 📚 文档搜索：在完整的UTCP规范中进行语义搜索
• ✅ 手动验证：根据v1.0.1规范验证UTCP手册，其中包含详细错误
• 🎨 代码生成：为HTTP、CLI、MCP、SSE协议生成UTCP手动模板
• 🔄 OpenAPI转换：自动将OpenAPI 3.0规范转换为UTCP手册
• 📝 示例库：天气API、GitHub、数据库、CLI工具的现成示例
• 💡 最佳实践：命名、身份验证和实施的内置指南

📦 安装

NPM

npm install -g utcp-docs

来源

git clone https://github.com/yourusername/utcp-docs-mcp-server.git
cd utcp-docs-mcp-server
npm install
npm run build
npm link

🔧 配置

适用于克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "utcp-docs": {
      "command": "utcp-docs",
      "env": {
        "DOCS_PATH": "/path/to/utcp-docs",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

用于游标IDE

增添 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "utcp-docs": {
      "command": "npx",
      "args": ["utcp-docs"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

环境变量

创建一个 .env 文件或在MCP配置中设置：

# OpenAI API Key (required for ask_utcp_expert tool)
OPENAI_API_KEY=sk-...

# Documentation path (default: current directory)
DOCS_PATH=.

# Server configuration
SERVER_NAME=utcp-docs
SERVER_VERSION=1.0.0
LOG_LEVEL=info

🛠️ 可用工具

🆕 1.咨询UTCP专家（LLM代理）

新 向OpenAI支持的代理询问有关UTCP的任何问题：

{
  "tool": "ask_utcp_expert",
  "arguments": {
    "question": "How do I authenticate with bearer tokens?"
  }
}

代理人：

• 对整个UTCP规范有深入了解
• 自动检索相关文档
• 通过代码示例提供详细解释
• 包括源引用
• 提供最佳实践和指导

示例问题：

• “什么是body_template，我什么时候应该使用它？”
• “显示一个使用OAuth2的完整HTTP工具示例”
• “如何将CLI命令链接在一起？”
• “为什么我的工具名称未通过验证？”

要求： OpenAI API密钥（集 OPENAI_API_KEY 环境变量）

______________________________________________________________________

2.搜索UTCP文档

搜索完整的UTCP规范：

{
  "tool": "search_utcp_docs",
  "arguments": {
    "query": "how to implement HTTP authentication",
    "section": "protocols",  // optional: introduction, protocols, guides, api
    "limit": 5               // optional: max results
  }
}

示例响应：

# Search Results for "HTTP authentication"

## Result 1: HTTP Protocol Authentication
**Section:** protocols
**Relevance:** 45

Authentication in HTTP protocols can be configured using the auth field...

3.验证UTCP手册

根据规范验证您的UTCP手册：

{
  "tool": "validate_utcp_manual",
  "arguments": {
    "manual": {
      "manual_version": "1.0.0",
      "utcp_version": "1.0.1",
      "tools": [...]
    }
  }
}

答复：

✅ Valid UTCP Manual
The manual passes all validation checks and conforms to UTCP v1.0.1 specification.

或者出现错误：

❌ Invalid UTCP Manual

## Errors
- /tools/0/name: Tool name "GetWeather" must use snake_case
- /tools/0/tool_call_template: HTTP template requires a URL

## Warnings
- /tools/0/description: Tool description should be at least 10 characters

4.生成UTCP手册

生成UTCP手册模板：

{
  "tool": "generate_utcp_manual",
  "arguments": {
    "tool_name": "get_weather",
    "description": "Get current weather for a location",
    "protocol": "http",
    "endpoint": "https://api.openweathermap.org/data/2.5/weather",
    "method": "GET",
    "parameters": {
      "location": {
        "type": "string",
        "description": "City name",
        "required": true
      }
    },
    "include_auth": true
  }
}

支持的协议：

• http -RESTful HTTP API
• cli -命令行工具
• mcp -模型上下文协议服务器
• sse -服务器发送的事件
• streamable_http -流式HTTP响应

5.将OpenAPI转换为UTCP

将OpenAPI 3.0规范转换为UTCP手册：

{
  "tool": "convert_openapi_to_utcp",
  "arguments": {
    "openapi_spec": {
      "openapi": "3.0.0",
      "info": { "title": "My API", "version": "1.0.0" },
      "paths": {
        "/users": {
          "get": {
            "operationId": "getUsers",
            "summary": "List users"
          }
        }
      }
    }
  }
}

6.获取UTCP示例

准备好使用示例UTCP手册：

{
  "tool": "get_utcp_examples",
  "arguments": {
    "use_case": "weather"  // weather, github, database, cli-tool
  }
}

可用示例：

• weather -OpenWeatherMap API集成
• github -GitHub REST API（转发，问题）
• database -通过MCP的数据库查询工具
• cli-tool -Git命令行包装器

7.获取最佳实践

获取UTCP实施最佳实践：

{
  "tool": "get_best_practices",
  "arguments": {
    "topic": "naming"  // naming, authentication, error-handling, testing, general
  }
}

📖 资源

服务器通过MCP提供这些资源：

🧪 使用示例

示例1：创建新的UTCP手册

// 1. Generate a template
const result = await callTool("generate_utcp_manual", {
  tool_name: "send_email",
  description: "Send an email via SendGrid API",
  protocol: "http",
  endpoint: "https://api.sendgrid.com/v3/mail/send",
  method: "POST",
  parameters: {
    to: { type: "string", description: "Recipient email", required: true },
    subject: { type: "string", description: "Email subject", required: true },
    body: { type: "string", description: "Email body", required: true }
  },
  include_auth: true
});

// 2. Validate the generated manual
const validation = await callTool("validate_utcp_manual", {
  manual: JSON.parse(result)
});

// 3. Get best practices for authentication
const practices = await callTool("get_best_practices", {
  topic: "authentication"
});

示例2：转换现有OpenAPI规范

// 1. Read your OpenAPI spec
const openApiSpec = JSON.parse(fs.readFileSync("api-spec.json"));

// 2. Convert to UTCP
const utcpManual = await callTool("convert_openapi_to_utcp", {
  openapi_spec: openApiSpec
});

// 3. Validate the result
const validation = await callTool("validate_utcp_manual", {
  manual: JSON.parse(utcpManual)
});

示例3：搜索文档

// Search for specific implementation details
const results = await callTool("search_utcp_docs", {
  query: "how to handle streaming responses",
  section: "protocols",
  limit: 3
});

// Get an example to reference
const example = await callTool("get_utcp_examples", {
  use_case: "github"
});

🏗️ 发展

设置

# Clone repository
git clone https://github.com/yourusername/utcp-docs-mcp-server.git
cd utcp-docs-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

项目结构

utcp-docs/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── types/
│   │   └── utcp.ts           # TypeScript types
│   ├── services/
│   │   ├── documentation.ts  # Documentation search
│   │   ├── validator.ts      # UTCP validation
│   │   ├── generator.ts      # Manual generation
│   │   └── converter.ts      # OpenAPI conversion
│   └── schemas/
│       └── utcp-manual.schema.json
├── docs/
│   └── examples/             # Example UTCP manuals
├── tests/
│   └── services/             # Unit tests
├── llms.txt                  # Complete UTCP documentation
└── package.json

📋 需求

• Node.js：20.x或更高
• TypeScript：5.3或更高
• MCP-SDK：1.0.4或更高版本

🤝 贡献

欢迎投稿！请按照以下步骤操作：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 为新功能编写测试
• 遵循TypeScript的最佳实践
• 更新API变更文档
• 在提交PR之前，确保所有测试都通过

📚 资源

UTCP资源

• UTCP网站
• UTCP规范
• UTCP与MCP比较

MCP资源

• 模型上下文协议
• MCP SDK文档
• MCP服务器存储库

🐛 故障排除

服务器未启动

问题： Error: Cannot find module 'ajv-formats'

解决方案：

npm install ajv-formats
npm run build

文档未加载

问题： Error loading llms.txt

解决方案： 确保 DOCS_PATH 环境变量指向正确的目录：

export DOCS_PATH=/path/to/utcp-docs

验证错误

问题： 工具名称验证失败

解决方案： 使用snake_case命名：

• ✅ get_user_data
• ❌ GetUserData
• ❌ getUserData

📄 许可证

MIT许可证-请参阅 许可证 详细信息文件

🙏 致谢

• UTCP团队 用于创建通用工具调用协议
• Anthropic 对于模型上下文协议
• 此项目的所有贡献者

📞 支持

• 问题:
• 讨论:
• 电子邮件: support@example.com

______________________________________________________________________

内置于❤️ 面向人工智能开发社区

*使UTCP实现更容易，一次一个工具。*