使用说明

项目简介

JANHMS_needle-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，它专注于文档管理和语义搜索。该服务器集成了 Needle (needle.xyz) 平台的服务，允许用户通过 LLM 客户端 (例如 Claude) 创建和管理文档集合，并将文档添加到集合中进行语义搜索。这使得 LLM 能够利用文档集合作为上下文信息，提升对话和问答能力。

主要功能点

文档集合管理: 支持创建、查看、删除和列出文档集合。
文档添加: 允许通过 URL 将文档添加到指定的文档集合中。
语义搜索: 在文档集合中执行语义搜索，查找与用户查询相关的文档内容。
工具集成: 通过 MCP 协议将上述功能以工具的形式暴露给 LLM 客户端，客户端可以通过调用这些工具来完成文档管理和搜索任务。
基于 Needle 平台: 利用 Needle 平台强大的文档处理和语义搜索能力。

安装步骤

克隆仓库:

git clone https://github.com/MCP-Mirror/JANHMS_needle-mcp.git
cd JANHMS_needle-mcp

安装 UV: 按照仓库 README.md 的指示，全局安装 UV。推荐使用 Homebrew (MacOS):
```
brew install uv
```
如果使用其他系统或方法，请确保 'uv' 命令在全局环境中可用。
配置 Claude Desktop (或其他 MCP 客户端): 根据仓库 README.md 的指引，找到 Claude Desktop 的配置文件 'claude_desktop_config.json' 所在目录：
- MacOS: '~/Library/Application Support/Claude/'
- Windows: '%APPDATA%/Claude/' 如果目录不存在，请手动创建。然后在该目录下创建或编辑 'claude_desktop_config.json' 文件。

服务器配置

在 'claude_desktop_config.json' 文件中，添加 'mcpServers' 配置项，用于指定 Needle MCP 服务器的信息。以下是一个配置示例，请根据实际情况修改路径和 API Key：

{
  "mcpServers": {
    "needle_mcp": {  // 服务器名称，客户端用于识别和调用
      "command": "uv", // 启动服务器的命令，这里使用 uv 运行 Python 脚本
      "args": [      // 命令参数
        "--directory",  // 指定工作目录
        "/path/to/needle-mcp", // **请替换为 needle-mcp 仓库的实际路径**
        "run",          // uv 命令的子命令，表示运行
        "src/needle_mcp/server.py" // 要运行的 Python 脚本路径
      ],
      "env": {        // 环境变量
        "NEEDLE_API_KEY": "your_needle_api_key" // **请替换为你的 Needle API Key**
      }
    }
  }
}

配置参数说明:

'"needle_mcp"': 服务器的名称，可以自定义，客户端会使用这个名称来引用该服务器。
'"command": "uv"': 指定用于启动服务器的命令。这里假设 'uv' 已全局安装。如果 'uv' 不可用或你想使用其他方式启动，请相应修改。例如，如果直接使用 'python' 运行，可以修改为 '"command": "python"'，并调整 '"args"' 中的脚本路径。
'"args"': 一个字符串数组，包含传递给 'command' 的参数。
- '"--directory", "/path/to/needle-mcp"': 指定 'uv' 的工作目录为 'needle-mcp' 仓库的根目录。务必将 '/path/to/needle-mcp' 替换为你的实际仓库路径。
- '"run", "src/needle_mcp/server.py"': 告诉 'uv' 运行 'src/needle_mcp/server.py' 脚本。
'"env"': 一个 JSON 对象，用于设置服务器运行时的环境变量。
- '"NEEDLE_API_KEY": "your_needle_api_key"': 必须替换为你在 needle.xyz 申请的 API Key。 这是访问 Needle 平台服务的凭证。

重要提示:

替换路径和 API Key: 请务必将配置文件中的 '/path/to/needle-mcp' 替换为你本地 'needle-mcp' 仓库的绝对路径，并将 '"your_needle_api_key"' 替换为你的真实 Needle API Key。
UV 安装: 确保 'uv' 命令在你的系统环境中可用。如果安装或配置 'uv' 遇到问题，请参考仓库 README.md 或 UV 的官方文档。
Claude Desktop 重启: 修改 'claude_desktop_config.json' 后，需要完全退出并重新启动 Claude Desktop 才能使配置生效。

基本使用方法

配置完成后，在 Claude Desktop (或其他 MCP 客户端) 中，你可以使用自然语言指令来调用 Needle MCP 服务器提供的工具，例如：

"创建一个名为 '技术文档' 的新集合"
"将这个文档添加到集合，链接是 https://needle-ai.com"
"在集合中搜索关于 AI 的信息"
"列出我所有的集合"

客户端会将这些自然语言指令转换为对 MCP 服务器工具的调用，服务器会执行相应的操作并将结果返回给客户端。具体可用的指令和工具描述请参考仓库 'src/needle_mcp/server.py' 文件中 'list_tools' 函数的定义。

关键词