{
  "markdown": "# Contraption Company MCP\n\nAn MCP (Model Context Protocol) server for [Contraption Company](https://contraption.co) essay, built on [Chroma Cloud](https://trychroma.com).\n\n## How to Install\n\nContraption Company MCP is available as a hosted MCP server with no authentication.\n\n| Field      | Value                        |\n| ---------- | ---------------------------- |\n| Server URL | `https://mcp.contraption.co`  |\n\n### How to configure in common clients\n\n<details>\n<summary><b>Cursor</b></summary>\n\nUse the deep link to install directly in Cursor: [Install Contraption Company MCP](cursor://anysphere.cursor-deeplink/mcp/install?name=contraption-company&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250cmFwdGlvbi5jbyJ9).\n\nOr, create or edit `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"contraption-company\": {\n      \"url\": \"https://mcp.contraption.co\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>ChatGPT</b></summary>\n\n1. Open **Settings → Connectors**.\n2. Click **Create new connector**.\n3. Set **MCP Server URL** to `https://mcp.contraption.co`.\n4. Leave authentication blank and save.\n\n</details>\n\n<details>\n<summary><b>VS Code (Copilot Chat MCP)</b></summary>\n\nCreate or edit `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"contraption-company\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.contraption.co\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Codex</b></summary>\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.contraption-company]\ncommand = \"npx\"\nargs = [\"mcp-remote\", \"--transport\", \"http\", \"https://mcp.contraption.co\"]\n```\n\n</details>\n\n<details>\n<summary><b>Claude Code</b></summary>\n\nRun in your terminal:\n\n```bash\nclaude mcp add --transport http contraption-company https://mcp.contraption.co\n```\n\n</details>\n\n<details>\n<summary><b>OpenAI SDK (Python)</b></summary>\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI()\n\nresponse = client.responses.create(\n    model=\"gpt-5\",\n    input=\"List the newest Contraption Company blog posts.\",\n    tools=[\n        {\n            \"type\": \"mcp\",\n            \"server_label\": \"contraption-company\",\n            \"server_url\": \"https://mcp.contraption.co\",\n            \"require_approval\": \"never\",\n        }\n    ],\n)\nprint(response)\n```\n\n</details>\n\n## Features\n\n- Search: Find posts and pages by query text\n- Automatic Indexing: Syncs with the blog API on startup and via scheduled polling\n- Full Content Access: Indexes all published posts and pages, including members-only content\n- Fast Performance: Powered by FastAPI and Chroma Cloud\n- Background Updates: Polls Ghost every few minutes for new, updated, or deleted posts and pages\n- Query Logging: Records searches in a dedicated Chroma collection for analysis\n- Docker Ready: Includes Dockerfile for easy deployment\n- Well Tested: Comprehensive test suite with pytest\n\n## Run Locally\n\n1. Clone and install:\n\n```bash\ngit clone <repository>\ncd mcp\nuv sync --all-extras\n```\n\n2. Configure environment:\n\n```bash\ncp .env.example .env\n# Edit .env with your credentials\n```\n\n3. Run the server:\n\n```bash\n./run.sh\n# Or: uv run python -m src.main\n```\n\n### Docker\n\n```bash\n# Build\ndocker build -t contraption-mcp .\n\n# Run\ndocker run -p 8000:8000 --env-file .env contraption-mcp\n\n# Or use docker-compose\ndocker-compose up\n```\n\n## Configuration\n\nRunning locally requires credentials for external services:\n\n- **Ghost Admin API Key**: From your Ghost Admin panel (Settings > Integrations)\n- **Chroma Cloud Credentials**: Tenant ID, Database, and API key from Chroma Cloud\n- **Chroma Query Collection (optional)**: Set `CHROMA_QUERY_COLLECTION` to override the default `queries` collection\n- **Voyage API Key**: Required to generate contextualized embeddings\n- **Ghost Blog URL**: Your Ghost blog's URL\n- **Polling Interval (optional)**: Set `POLL_INTERVAL_SECONDS` to override the default 5 minute sync cadence\n- Members-only content and query logging are enabled by default. Ensure your privacy policy and access controls cover both.\n\n## Support and Privacy\n\n- **Support**: `hello@contraption.co`\n- **Privacy policy**: https://www.contraption.co/privacy/\n- Query logging and members-only content are enabled, and the privacy policy must cover both.\n\n## MCP Tools\n\n- `fetch(id)`: Fetch a single post or page using the canonical URL as the identifier. Provide the `id` returned by `list_posts`/`search` (which is the canonical URL); slugs and shorthand schemes are also accepted but responses always resolve to full URLs.\n- `list_posts(sort_by, page, limit)`: List posts with pagination, returning canonical URLs as identifiers\n- `search(query, limit)`: Search posts and pages by query text; returns canonical URLs for result IDs\n\n## API Endpoints\n\n- `GET /`: Server info (redirects to GitHub repo for non-MCP requests)\n- `GET /health`: Health check\n- `GET /debug/search`: Debug search endpoint (see `/debug/docs` for Swagger UI)\n- `/mcp/*`: MCP protocol endpoints\n\n### Background Sync\n\nThe server polls the Ghost Admin API every 5 minutes to detect new, updated, or deleted posts and pages. Adjust the cadence by setting the `POLL_INTERVAL_SECONDS` environment variable.\n\n## Development\n\n```bash\n# Install dev dependencies\nmake dev\n\n# Run tests\nmake test\n\n# Lint and format\nmake format lint\n\n# Run all checks\nmake check\n```\n\n## License\n\nMIT\n",
  "bytes": 5270,
  "sha": "ae2f0ec261e246d2138a5221c3cea610a72532c9b9d7aa0a9109e0343d575379",
  "repo_slug": "contraptionco/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_co_contraption_mcp_2235aa95/readme"
}