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 Key：Ghost管理パネル（Settings > Integrations）から取得します
• Chroma Cloud Credentials：Chroma CloudのテナントID、データベース、APIキー
• Chroma Query Collection（任意）：CHROMA_QUERY_COLLECTIONを設定すると、デフォルトのqueriesコレクションを変更できます
• Voyage API Key：コンテキスト化された埋め込みを生成するために必要です
• Ghost Blog URL：GhostブログのURL
• ポーリング間隔（任意）：POLL_INTERVAL_SECONDSを設定すると、デフォルトの5分間隔の同期を変更できます
• 会員限定コンテンツとクエリのログ記録は、デフォルトで有効になっています。プライバシーポリシーとアクセス制御の両方に、これらが反映されていることを確認してください。

サポートとプライバシー

• サポート：[email protected]
• プライバシーポリシー：https://www.contraption.co/privacy/
• クエリのログ記録と会員限定コンテンツは有効になっているため、プライバシーポリシーで両方を対象にする必要があります。

MCPツール

• fetch(id)：正規URLを識別子として、単一の投稿またはページを取得します。list_posts／searchが返すid（正規URL）を指定してください。スラッグや省略形のスキームも受け付けますが、レスポンスでは常に完全な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