contraption

Contraption Company MCP

适用于 Contraption Company 文章的 MCP（Model Context Protocol）服务，基于 Chroma Cloud 构建。

安装方法

Contraption Company MCP 提供托管 MCP 服务，无需身份验证。

在常用客户端中配置

{
  "mcpServers": {
    "contraption-company": {
      "url": "https://mcp.contraption.co"
    }
  }
}

{
  "servers": {
    "contraption-company": {
      "type": "http",
      "url": "https://mcp.contraption.co"
    }
  }
}

[mcp_servers.contraption-company]
command = "npx"
args = ["mcp-remote", "--transport", "http", "https://mcp.contraption.co"]

claude mcp add --transport http contraption-company https://mcp.contraption.co

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="List the newest Contraption Company blog posts.",
    tools=[
        {
            "type": "mcp",
            "server_label": "contraption-company",
            "server_url": "https://mcp.contraption.co",
            "require_approval": "never",
        }
    ],
)
print(response)

功能

• 搜索：根据查询文本查找文章和页面
• 自动索引：启动时及通过定时轮询与博客 API 同步
• 完整内容访问：索引所有已发布的文章和页面，包括仅限会员访问的内容
• 高性能：由 FastAPI 和 Chroma Cloud 提供支持
• 后台更新：每隔几分钟轮询 Ghost，查找新增、更新或已删除的文章和页面
• 查询记录：将搜索记录到专用的 Chroma 集合中以供分析
• 支持 Docker：提供 Dockerfile，便于部署
• 测试完善：包含全面的 pytest 测试套件

本地运行

1. 克隆并安装：

git clone <repository>
cd mcp
uv sync --all-extras

2. 配置环境：

cp .env.example .env
# Edit .env with your credentials

3. 运行服务：

./run.sh
# Or: uv run python -m src.main

Docker

# Build
docker build -t contraption-mcp .

# Run
docker run -p 8000:8000 --env-file .env contraption-mcp

# Or use docker-compose
docker-compose up

配置

本地运行需要外部服务的凭据：

• Ghost Admin API 密钥：从 Ghost 管理面板获取（Settings > Integrations）
• Chroma Cloud 凭据：从 Chroma Cloud 获取租户 ID、数据库和 API 密钥
• Chroma 查询集合（可选）：设置 CHROMA_QUERY_COLLECTION 以覆盖默认的 queries 集合
• Voyage API 密钥：生成上下文化嵌入所需
• Ghost 博客 URL：你的 Ghost 博客 URL
• 轮询间隔（可选）：设置 POLL_INTERVAL_SECONDS 以覆盖默认的 5 分钟同步间隔
• 默认启用仅限会员访问的内容和查询记录。请确保隐私政策和访问控制涵盖这两项。

支持与隐私

• 支持：[email protected]
• 隐私政策：https://www.contraption.co/privacy/
• 查询记录和仅限会员访问的内容均已启用，隐私政策必须涵盖这两项。

MCP 工具

• fetch(id)：使用规范 URL 作为标识符获取单篇文章或页面。请提供 list_posts/search 返回的 id（即规范 URL）；也接受 slug 和简写方案，但响应始终会解析为完整 URL。
• list_posts(sort_by, page, limit)：分页列出文章，并返回作为标识符的规范 URL
• search(query, limit)：根据查询文本搜索文章和页面；结果 ID 返回规范 URL

API 端点

• GET /：服务信息（对于非 MCP 请求，会重定向到 GitHub 仓库）
• GET /health：健康检查
• GET /debug/search：搜索调试端点（Swagger UI 见 /debug/docs）
• /mcp/*：MCP 协议端点

后台同步

服务每 5 分钟轮询一次 Ghost Admin API，以检测新增、更新或已删除的文章和页面。设置环境变量 POLL_INTERVAL_SECONDS 可调整轮询间隔。

开发

# Install dev dependencies
make dev

# Run tests
make test

# Lint and format
make format lint

# Run all checks
make check

许可证

MIT