项目简介

Gandalf 是一个基于 Model Context Protocol (MCP) 的服务器，旨在为AI辅助开发工具（如 Cursor、Claude Code）提供智能上下文。它通过聚合、过滤和管理用户在这些工具中的对话历史，帮助大型语言模型（LLM）更准确地理解开发者的意图和项目背景。Gandalf 遵循 MCP 2025-06-18 协议，通过 JSON-RPC 与 MCP 客户端通信，提供工具调用、信息查询等功能。

主要功能点

MCP 协议合规: 完全符合 Model Context Protocol 规范，使用 JSON-RPC 进行通信。
工具注册与管理: 动态注册和管理各种工具，供 LLM 客户端调用。
对话聚合: 自动检测并整合来自 Cursor 和 Claude Code 等开发工具的对话数据库。
智能上下文提取: 支持基于关键词的对话搜索和过滤，帮助 AI 快速定位相关信息。
CLI 管理: 提供命令行接口，方便用户启动、停止、检查服务器状态以及管理工具注册。
零配置: 智能默认设置，开箱即用，支持跨平台运行。

安装步骤

准备环境:
- 确保已安装 Python 3.10 或更高版本。
- 确保已安装 Git。
- 推荐使用支持 MCP 协议的集成开发环境 (IDE)，如 Cursor 或 Claude Code。

克隆仓库:

git clone https://github.com/bluekornchips/gandalf.git
cd gandalf

安装和配置: 运行安装脚本，它将自动检测开发工具并设置 Gandalf 注册表。
```
./gandalf.sh --install
```

服务器配置

MCP 客户端需要配置服务器的启动命令和参数才能建立连接。以下是针对 Gandalf MCP 服务器的配置信息（JSON 格式）：

{
  "serverName": "Gandalf",
  "command": "./gandalf.sh",
  "args": ["--server", "start"],
  "description": "启动 Gandalf MCP 服务器，聚合开发工具对话历史。",
  "protocolVersion": "2025-06-18"
}

'serverName': 服务器的名称，此处为 "Gandalf"。
'command': 启动服务器的主命令，指向仓库根目录下的 'gandalf.sh' 脚本。
'args': 传递给命令的参数，'--server start' 用于启动 MCP 服务器。
'description': 对服务器功能的简要描述。
'protocolVersion': 服务器支持的 MCP 协议版本。

基本使用方法

安装并启动服务器后，您可以通过 MCP 客户端调用 Gandalf 提供的工具。

启动服务器: 在您的终端中执行以下命令来启动 Gandalf 服务器：
```
./gandalf.sh --server start
```
测试服务器连接（通过 MCP 客户端调用 'echo' 工具）: 在您的 MCP 客户端中，您可以调用 'echo' 工具来测试服务器是否正常响应。例如，如果您的客户端支持类似概念，可以这样调用：
```
# 客户端逻辑表示，非实际代码：
call_tool("echo", {"message": "Hello, Gandalf!"})
```
服务器将返回一个 'ToolResult'，其中包含类似 "Echo: Hello, Gandalf!" 的文本。
获取服务器信息（通过 MCP 客户端调用 'get_server_info' 工具）: 要了解 Gandalf 服务器的详细信息，可以在客户端中调用 'get_server_info' 工具：
```
# 客户端逻辑表示：
call_tool("get_server_info", {})
```
服务器将返回一个 'ToolResult'，其中包含服务器的名称、版本、描述和能力等信息。

回忆对话历史（通过 MCP 客户端调用 'recall_conversations' 工具）: 这是 Gandalf 的核心功能，用于获取聚合的对话上下文。您可以带或不带参数调用此工具：

# 客户端逻辑表示：
# 获取所有可用的对话历史（默认数量限制）
call_tool("recall_conversations", {})

# 带有关键词搜索和限制的结果数量：
call_tool("recall_conversations", {"keywords": "python debugging", "limit": 10})

# 仅包含用户提示，不包含 AI 生成内容：
call_tool("recall_conversations", {"include_prompts": true, "include_generations": false})

服务器将返回 JSON 格式的聚合对话历史和相关元数据。

停止服务器: 在终端中执行以下命令来停止 Gandalf 服务器：

./gandalf.sh --server stop