HowCanI MCP 服务端

关键词

LLM 集成JSON-RPC工具注册向量检索Embedding

使用说明（简明、实用信息）

  • 项目简介
    • HowCanI 的 MCP 服务端实现，提供遵循 MCP 的接口用以向大型语言模型（LLM）客户端提供资源数据、可调用工具以及可渲染的 Prompt 模板，通过 JSON-RPC 协议进行请求/响应通信，并在服务端进行会话管理与能力声明，便于 LLM 与应用后端进行安全、可扩展的上下文服务对接。
  • 主要功能点
    • MCP 端点与传输：通过 /mcp 提供 MCP 服务，使用 WebStandardStreamableHTTPTransport 进行 JSON-RPC 通信。
    • 工具注册与执行：注册如 search_items、list_items、get_item、list_tags、create_item、update_item、get_related_items、create_item 等工具，LLM 可以按需调用。
    • 资源与数据访问：对 Items、Tags、Users 等资源提供查询、创建、更新、删除等操作，支持分页、过滤、向量检索等能力。
    • 向量嵌入与语义检索：集成 EmbeddingService，支持通过外部服务生成嵌入向量，并在必要时进行向量近邻检索。
    • 会话与权限：内置会话处理与基本权限校验，部分工具需要 Bearer Token（如更新/创建等）。
    • 兼容性与扩展性：代码结构分明，具备 migrations、数据库封装、服务层、仓储层等分层设计，方便扩展新工具与数据模型。
  • 安装步骤
    • 环境准备：安装 Bun、确保 SQLite 数据库可写。
    • 依赖安装与编译运行（简要流程）：
      • bun install
      • bun run dev
    • 说明：应用在启动时会自动执行数据库迁移，并初始化定时任务（cron）、备份等服务。
  • 服务器配置（MCP 客户端配置必备信息，配置以 JSON 格式提供给 MCP 客户端）
    • serverName: howcani
    • command: bun
    • args: ["run", "dev"]
    • 说明：这是用于启动 MCP 服务器的命令及参数集合。实际 MCP 客户端连接时需要使用服务器的网络地址与端口（默认 3000，若调整请在环境变量或启动参数中修改），并可在请求中通过 Authorization 头携带 Bearer Token（若需要 API Token）。
    • 连接信息概要（供 MCP 客户端参考，不是代码）：服务器名称 howcani，启动命令 bun run dev，监听端口默认 3000，MCP 端点 URL 为 http://<服务器地址>:3000/mcp。
    • 客户端通常还需设置的传输头信息（示意性描述）：如在需要鉴权时的 Authorization: Bearer <token>，具体 token 的获取与使用由客户端实现方决定。
  • 基本使用方法
      1. 启动服务器：按照安装步骤在服务器主机上运行 bun run dev，确保数据库初始化完成。
      1. MCP 客户端接入：在 MCP 客户端（如 Claude Code/Claude Desktop）配置文件中注册一个新的 MCP 服务器，type 设为 http，url 指向 http://<服务器地址>:3000/mcp，必要时添加请求头（如 Authorization）以提供访问令牌。
      1. 调用工具与获取资源：通过 MCP 客户端向服务器的工具列表调用，例如搜索、获取条目、更新条目、获取相关/重复项等，服务器端会执行对应的业务逻辑并返回结构化结果。
      1. 安全与权限：若某些工具需要鉴权，请在调用时提供有效的 Bearer Token，服务器将进行验证并返回相应的错误信息（未授权、无权限等）。
      1. 维护与扩展：如需扩展新的工具、资源或 Prompts，可在 server.ts 中注册新的 tool，并实现相应的服务逻辑。

服务器信息

访问项目