使用说明

项目简介

这是一个基于 MCP 的服务器端实现，承载并管理“命令定义”和“分析报告”的资源，提供三大核心能力：

• 资源管理：命令与分析报告的读取、列举与查询。
• 工具注册与执行：通过 MCP 的工具接口，LLM 可以调用搜索、获取命令、获取报告等操作。
• Prompt 与上下文：可渲染与返回与命令/报告相关的内容，帮助 LLM 构造对话上下文。

本仓库实现了两种传输模式的 MCP 服务器：

• stdio 模式（本地/SSH 场景）通过 ai-command-tool 命令行启动
• SSE 模式（远程多用户访问）通过 ai-command-tool-server 启动 HTTP SSE 服务

上述模式都具备会话管理、能力声明以及对客户端请求的 JSON-RPC 风格响应能力，符合 MCP 服务器的核心职责。

主要功能点

• 双模式传输
  • stdio：本地/SSH 交互
  • SSE：通过 HTTP 长连接实现服务端推送与多客户端并发
• 三层搜索能力
  • Tier 1：通过命名（文件名）进行快速匹配
  • Tier 2：基于命令及描述的语义/模糊搜索
  • Tier 3：跨命令的历史分析报告搜索
• 资源与工具管理
  • list_commands、get_command、search_commands 等工具
  • list_command_reports、search_reports、get_report 等工具
  • report_feedback、upload_command 等工具，支持命令与报告的上传与更新
• 报告与命令的版本管理
  • 报告/命令上传前进行同步（与远端数据库对齐），失败会阻止实际写入
  • 支持冲突时的版本自动后缀处理，确保唯一性
• 安全与容错
  • 路径校验、前缀过滤、输入校验
  • 连接健康心跳、错误处理与日志记录

安装与运行（简明步骤，可直接执行）

• 安装
  • 全局安装：npm install -g @elliotding/ai-command-tool-mcp@latest
• 本地测试（stdio 模式）
  • 按 README 快速启动，指定 CONFIG_PATH 配置文件路径后运行 ai-command-tool
• 远程测试（SSE 模式）
  • 直接启动 ai-command-tool-server，监听端口并通过 /health、/sse 进行健康与连接测试

注：仓库提供了详细的本地与生产部署说明，包含系统服务、Nginx 代理以及健康接口等内容。

服务器配置（MCP 客户端的连接信息）

MCP 客户端连接该服务器时，至少需要提供：

• server 名称，用于标识一个 MCP 服务端实例
• 启动命令及参数，便于在本地或远程执行连接
• 传输模式信息（stdio 或 sse）

示例 JSON（请按实际环境替换路径与域名）：

• stdio 模式（本地/SSH 情况下的 Cursor 配置）： { "mcpServers": { "ai-command-tool": { "command": "ai-command-tool", "args": [] } } } 说明：此配置让客户端通过 stdio 启动 ai-command-tool，若需要通过配置文件路径提供配置，请将 CONFIG_PATH 设置到环境变量中，例如通过 Cursor 配置中的 env 配置实现。

• SSE 模式（远程 HTTP 服务器，带有 SSE 传输）： { "mcpServers": { "ai-command-tool": { "url": "https://your-domain.com/mcp/sse", "transport": "sse" } } } 说明：该模式下客户端通过 SSE 接口与服务器进行通信，适合多用户并发场景。服务端提供 /health 进行健康检查，/sse 建立长连接。

基本使用方法（入门级操作指导）

• 选择传输模式
  • 本地开发与调试：使用 stdio 模式（ai-command-tool）
  • 生产环境与多用户：使用 SSE 模式（ai-command-tool-server）
• 与 LLM 的对接流程
  • 通过 MCP 的工具接口进行查询、命令获取、命名与报告查询等操作
  • 上传命令与报告时，先执行远端同步（确保元数据一致），再写入本地/远端存储
• 使用建议
  • 先通过 search_commands、list_commands 界面化浏览命令集合
  • 使用 get_command 获取命令详情与内容，了解使用方式
  • 使用 search_reports、list_command_reports 查找分析报告及其链接
  • 当需要将分析报告上传时，使用 report_feedback 或 upload_command 进行交互式上传，确保合规与版本控制

如要了解更详细的配置项、工具输入输出以及错误处理，请参考仓库中的文档与代码注释。