内容
# akamai-techdocs-mcp
一款 MCP 服务器，为 AI 助手（Claude Desktop, Claude Code, Cursor, …）提供跨 Akamai Cloud（Linode）和 Akamai Functions 文档的全文搜索功能，以及通过 URL 获取整个文档页面的能力。
服务器自带预建的 SQLite 索引，因此安装后立即生效，无需联网。CI 工作流会从 [`sources.yaml`](./sources.yaml) 中声明的 URL 重新构建索引 - 将新 URL 添加到该文件是扩展覆盖范围的主要方式。
## 包含的来源
大约 1,500 个可搜索的片段，涵盖：
- **Linode API** - 完整的 OpenAPI 规范（~449 个操作：Linodes、LKE、托管数据库、对象存储、VPC、NodeBalancers、防火墙、DNS、账户/账单等）。
- **Linode 开源项目** - [github.com/linode](https://github.com/linode) 中每个非 fork 仓库的 README（91 个仓库）：SDK（`linodego`、`linode_api4-python`）、Linode CLI、IaC 提供者（Terraform、Ansible、Packer）、Kubernetes/LKE 运算符（云控制器管理器、CSI/COSI 驱动器、集群 API、Karpenter）、Akamai 应用平台（APL）、AI 快速入门等。
- **Spin Framework v3** - Akamai Functions 上游的 WebAssembly 应用框架（快速入门、触发器、语言指南、清单参考、部署）。
- **生态系统参考** - KEDA（事件驱动的自动扩展）、Karpenter（节点自动扩展）和 HashiCorp Terraform 模块教程。
调用 `list_sources` 可在任何 MCP 客户端上查看已发货索引的确切内容，包括 `url_count` 和 `last_crawled_at`。
> 注意：`techdocs.akamai.com` 上的手动编写的文档未被索引 - Akamai 的 Bot Manager 对爬虫（本地和 CI）返回 HTTP 403。Linode API 内容改编自 GitHub 上的上游 OpenAPI 规范。
## 安装
您需要安装 [`uv`](https://docs.astral.sh/uv/)。请选择以下适合您运行服务器的方式。
### 选项 1 - `uvx`，无需安装（推荐用于试用）
将您的 MCP 客户端指向 `uvx` 并让其在每次启动时获取并缓存：
```sh
uvx --from git+https://github.com/samkarande/akamai-techdocs-mcp akamai-techdocs-mcp
```
这种方式构建的轮子不附带捆绑索引；服务器的自动更新程序会在首次运行时从最新的 GitHub Release 下载 `index.sqlite`。
### 选项 2 - 从 GitHub Release 安装固定版本
每个版本都附带一个可安装的轮子，包含新构建的索引。 从 [最新版本](https://github.com/samkarande/akamai-techdocs-mcp/releases/latest) 获取轮子 URL 并安装它（文件名包含版本号）：
```sh
uv tool install --reinstall \
https://github.com/samkarande/akamai-techdocs-mcp/releases/download/<tag>/akamai_techdocs_mcp-<version>-py3-none-any.whl
```
这将 `akamai-techdocs-mcp` 放在您的 PATH 中（通常是 `~/.local/bin/akamai-techdocs-mcp`）。
### 选项 3 - 从源代码本地构建（开发流程）
```sh
git clone https://github.com/samkarande/akamai-techdocs-mcp.git
cd akamai-techdocs-mcp
# 1. 构建预建索引（运行一次，~10 秒用于 Spin 文档）。
uv run python -m crawler.build_index
# 2. 构建一个捆绑索引的轮子。
uv build --wheel
# 3. 在全局范围内安装 CLI 工具。
uv tool install --reinstall ./dist/akamai_techdocs_mcp-*.whl
```
## 连接到您的 AI 客户端
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或平台等效文件。
**如果您使用了选项 1（uvx，无需安装）：**
```json
{
"mcpServers": {
"akamai-techdocs": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/samkarande/akamai-techdocs-mcp",
"akamai-techdocs-mcp"
]
}
}
}
```
**如果您使用了选项 2 或 3（已安装的轮子）：**
```json
{
"mcpServers": {
"akamai-techdocs": {
"command": "akamai-techdocs-mcp"
}
}
}
```
如果 `akamai-techdocs-mcp` 不在 Claude Desktop 的 PATH 中，请使用 `which akamai-techdocs-mcp` 的绝对路径代替。
完全退出并重新打开 Claude Desktop。
### Claude Code
如果已安装（选项 2/3）：
```sh
claude mcp add akamai-techdocs -- akamai-techdocs-mcp
```
或零安装（选项 1）：
```sh
claude mcp add akamai-techdocs -- \
uvx --from git+https://github.com/samkarande/akamai-techdocs-mcp akamai-techdocs-mcp
```
### Cursor / 其他 MCP 客户端
相同的形式 - `command: akamai-techdocs-mcp`，无参数，无环境变量。
## 试用
在您的助手上询问类似的问题：
- *"使用 akamai-techdocs 查看 Linode API 调用以创建 LKE Kubernetes 集群。*"
- *"在 akamai-techdocs 中搜索 `linode_object_storage_bucket` Terraform 资源。*"
- *"如何使用 linodego Go SDK 创建实例？请查看 akamai-techdocs。*"
- *"查看如何用 Rust 编写 Spin 组件。*"
- *"列出 akamai-techdocs 索引的产品。*"
每个结果都包含源 URL，以便模型可以（并且应该）在答案中引用它。
## 示例
[`examples/`](./examples) 目录包含适用于常见 Akamai Cloud 任务的可操作、复制粘贴的解决方案。每个示例都是一个单独的文件夹，包含原始自然语言 **prompt** (`prompt.txt`)、可运行代码和解释设计的 README。
| # | 示例 | 堆栈 |
|---|---|---|
| 1 | [`01-nodebalancer-vpc-apache`](./examples/01-nodebalancer-vpc-apache) | Terraform — Apache 网络层（2× nano）位于新 VPC 后的 NodeBalancer |
| 2 | [`02-object-storage-private-bucket`](./examples/02-object-storage-private-bucket) | Terraform — 私有（非公开）对象存储桶 |
| 3 | [`03-managed-mysql-database`](./examples/03-managed-mysql-database) | Terraform — 托管 MySQL 8 数据库 |
| 4 | [`04-lke-autoscaling-cluster`](./examples/04-lke-autoscaling-cluster) | Terraform + k8s — 具有 2 个 Pod/节点的负载均衡 LKE 集群 |
这些示例通过连接到此 MCP 服务器的助手生成；每个文件夹中的 `prompt.txt` 是确切的请求。它们是参考代码 - 在应用到真实账户之前请审查。
## 服务器暴露的工具
- **`search_docs(query, product?, limit?)`** - 跨所有块的 BM25 全文搜索。返回 `{url, doc_title, heading_path, snippet, source_id, product, version, rank}` 的排名列表，并在片段中突出显示 `«match»`。
- **`get_doc(url)`** - 从块中重新组装一个文档页面的完整 Markdown。返回元数据 + Markdown 正文。
- **`list_sources()`** - 索引产品的目录，包含 `url_count`、`tombstoned_count` 和 `last_crawled_at`。适用于查找 `search_docs` 接受的精确 `product` 过滤器值。
每个响应都包含一个索引元数据块（schema_version、manifest_version、manifest_sha、built_at、crawler_version），因此可见性是可观察的。
## 将 URL 添加到索引
编辑 [`sources.yaml`](./sources.yaml)。打开一个 PR。周度的 CI 工作流（[`build-index.yml`](.github/workflows/build-index.yml)）会用您的 URL 重新构建索引；用户在下一次刷新时获取新内容 - 无需软件包升级。
清单加载器强制执行的约束：
- URL 必须是 HTTPS。
- 每个 URL 的主机名必须与其源的 `domain` 匹配。
- 每个源 `domain` 必须存在于 `allowed_domains` 中。
- `schema_version` 必须与加载器支持的版本匹配。
## 在本地重建索引
```sh
uv run python -m crawler.build_index --verbose
```
检查输出：
```sh
uv run python -c "
import sqlite3
c = sqlite3.connect('dist/index.sqlite')
for r in c.execute('SELECT key, value FROM meta'): print(r)
print(c.execute('SELECT COUNT(*) FROM chunks').fetchone()[0], 'chunks')
"
```
## 开发
```sh
uv sync
uv run pytest
uv run ruff check .
uv run pyright
```
仓库使用 `.python-version` 中的 Python 3.13，因为 Python 3.13.3+ 和 3.14 静默跳过 hatchling 的可编辑安装 `.pth` 文件（它以 `_` 开头，在 CVE 补丁后被视为隐藏）。仓库根目录的 `conftest.py` 将 `src/` 放在 `sys.path` 上以进行测试，作为本地变通方法。轮子（用户安装）不受影响。
## 切割版本
两个工作流发布到 GitHub Releases：
- **[`build-index.yml`](.github/workflows/build-index.yml)** 每个星期一 06:00 UTC 运行（按需通过 `workflow_dispatch`）。它重建 `index.sqlite`，用该索引打包一个轮子，并发布两者，标签为 `index-2026-06-08`。这是保持已安装副本的文档更新。
- **[`release.yml`](.github/workflows/release.yml)** 用于切割版本发布。有两种触发方式:
```sh
# 基于标签（首选）
git tag v0.1.0
git push origin v0.1.0
# 或通过 GitHub UI / CLI 手动
gh workflow run release.yml -f version=0.1.0
```
它构建索引，构建一个文件名中包含版本的轮子 (`akamai_techdocs_mcp-0.1.0-py3-none-any.whl`)，并创建一个名为 `v0.1.0` 的版本。pyproject 版本仅在运行器中编辑；仓库本身保持不变。
## 自动更新
服务器启动时，它会检查 GitHub Releases 中是否有比本地缓存（`~/.cache/akamai-techdocs-mcp/`）中已有的版本更新的版本。如果存在，它会下载 `index.sqlite` + `index.sqlite.sha256`，验证校验和，验证模式，然后原子地将文件交换到位。
- 更新是**尽力而为**：任何故障（离线、速率限制、模式不匹配等）都会记录到 stderr 并回退到磁盘上已有的索引。服务器启动时绝不会因更新而阻塞超过几秒钟。
- 新下载的索引**在下一次服务器重启时生效** - 您的 MCP 客户端（Claude Desktop / Code）在应用程序重启时重启服务器，这通常足够了。
- 在服务器环境中设置 `AKAMAI_MCP_OFFLINE=1` 以完全跳过检查。
- 通过 `AKAMAI_MCP_RELEASES_REPO=owner/repo` 指向不同仓库的版本。
周度 [`build-index.yml`](.github/workflows/build-index.yml) 工作流会生成这些版本；运行安装轮子的用户会自动获取新鲜内容。
## 已知限制
- **`techdocs.akamai.com` 未被索引** - 参见上面的“包含的来源”。Akamai 的 Bot Manager 对爬虫（本地和 CI）返回 HTTP 403，因此 Linode API 内容改编自 GitHub 上的上游 OpenAPI 规范。
- **不支持热交换新下载的索引。** 运行的服务器保持旧的 SQLite 连接打开；新文件仅在下一次启动时可见。对于大多数 MCP 客户端，这是一个无关紧要的问题，因为它们在应用程序重启时重启服务器。
## 许可证
GPL-3.0-only。参见 [LICENSE](./LICENSE)。
