使用说明

项目简介

TheAlmanac 是一个基于 Model Context Protocol (MCP) 构建的文档助手，旨在帮助程序员更方便地访问最新的 API 和软件文档。它通过 MCP 协议向 LLM 客户端提供结构化的文档访问能力，使 LLM 能够理解和利用文档内容。

主要功能点

文档抓取与存储：自动从指定 URL 下载并本地存储文档，支持多种文档源。
文档检索：提供快速的文档内容搜索功能，可以搜索所有文档或指定来源的文档。
MCP 服务器：内置 HTTP 和 Stdio 服务器，通过 MCP 协议向 LLM 客户端暴露文档访问工具。
资源管理：支持文档来源的添加、移除和列表查看。
工具集成：提供 'search_documentation', 'get_documentation', 'download_documentation', 'list_documentation' 等 MCP 工具，方便 LLM 调用。

安装步骤

克隆仓库

git clone https://github.com/SaharCarmel/TheAlmanac.git
cd TheAlmanac

安装依赖

建议使用 'uv' 包管理器安装依赖，如果未安装请先安装 'uv'。

# 安装 uv (如果未安装)
pip install uv
# 使用 uv 安装项目依赖
uv pip install -e .

服务器配置

TheAlmanac 可以作为 MCP 服务器与支持 MCP 协议的 LLM 客户端（如 Claude for Desktop）集成。以下是配置 Claude for Desktop 连接 TheAlmanac MCP 服务器的示例配置信息：

{
  "mcpServers": {
    "the-almanac": {
      "command": "/path/to/python",  // Python 解释器路径，请替换为实际路径
      "args": [
        "-m",
        "almanac.cli.commands",  // 运行 TheAlmanac 服务器的模块
        "serve",                 // 启动服务器命令
        "--transport",           // 指定传输协议
        "stdio"                  // 使用 Stdio 协议，适用于 MCP 客户端
      ]
    }
  }
}

配置参数说明：

server name: '"the-almanac"' (服务器名称，在客户端中用于标识和调用)
command: Python 解释器的完整路径。请务必替换 '/path/to/python' 为您系统上 Python 解释器的实际路径。可以使用 'which python3' 或 'where python' 命令查找。
args: 启动 TheAlmanac MCP 服务器的参数列表，无需修改。

配置步骤：

找到 Claude for Desktop 的配置文件 'claude_desktop_config.json'，通常位于：
- macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
- Windows: '%APPDATA%\Claude\claude_desktop_config.json'
- Linux: '~/.config/Claude/claude_desktop_config.json'
编辑 'claude_desktop_config.json' 文件，在 'mcpServers' 字段中添加上述 JSON 配置。如果 'mcpServers' 字段不存在，请手动创建。
重启 Claude for Desktop。
在 Claude for Desktop 界面中，查找工具图标（通常是锤子或插件图标），即可访问 TheAlmanac 提供的文档工具。

基本使用方法

TheAlmanac 提供命令行界面 (CLI) 用于管理文档源和启动服务器。

1. 管理文档源：

添加文档源:

almanac add <source_name> <documentation_url>
# 例如: almanac add python https://docs.python.org/3/

列出文档源:
```
almanac list
```

移除文档源:

almanac remove <source_name>
# 例如: almanac remove python

下载文档:

almanac download <source_name>
# 例如: almanac download python
# 下载所有文档源: almanac download

2. 搜索文档：

almanac search <query> --source <source_name>
# 例如:
# 搜索所有文档: almanac search "context manager"
# 搜索 Python 文档: almanac search "context manager" --source python

3. 启动 MCP 服务器：

使用 Stdio 传输 (推荐 MCP 客户端):

almanac serve --transport stdio

使用 HTTP 传输 (直接 API 访问):

almanac serve --transport http --host 0.0.0.0 --port 9000

MCP 工具列表：

TheAlmanac 提供以下 MCP 工具，可通过 MCP 客户端调用：

'search_documentation': 在文档中搜索相关信息。
'get_documentation': 获取指定文档或章节的内容。
'download_documentation': 下载新的文档源（异步任务）。
'list_documentation': 列出可用的文档源。
'get_task_status': 获取异步任务的状态。

关键词