cairn

CAIRN — Create Any Integration, Run Naturally

Scaffold production-ready MCP servers for any domain. Part of the Alpine Toolkit.

Source: https://github.com/Percona-Lab/CAIRN Release: https://github.com/Percona-Lab/CAIRN/releases/latest

---

Project Types

1. API Integration

Wrap an external REST API as MCP tools. Generates a connector class (handles auth + HTTP) and an MCP server that exposes connector methods as tools. Based on the IBEX pattern (Slack, Jira, Notion connectors).

Generated files (Python):

• connector.py — API client class with auth headers + request helper
• mcp_server.py — FastMCP server wrapping connector methods as tools
• pyproject.toml, .env.example, README.md

Generated files (Node.js):

• src/connector.js — API client with auth + fetch helper
• src/mcp-server.js — @modelcontextprotocol/sdk server
• package.json, .env.example, README.md

2. Doc Search

Semantic search over GitHub repos containing Markdown documentation. The percona-dk pattern: clone repos, chunk markdown, embed in ChromaDB, expose via MCP + REST API. Includes a polished cross-platform installer with stack selection, progress bars, and AI client auto-detection.

Generated files (Python):

• mcp_server.py — FastMCP server with auto-refresh
• ingest.py — Incremental ingestion with file hashing
• server.py — FastAPI REST API
• source_registry.py — Source suggestions
• installer.py — Cross-platform interactive installer
• Bootstrap scripts, pyproject.toml, .env.example, README.md

3. Starter

Minimal MCP server with one example hello tool. User fills in the rest. Smallest possible starting point for custom MCP servers.

Generated files (Python):

• mcp_server.py — FastMCP server with one example tool
• pyproject.toml, README.md

---

How to Use

Option 1: Download and run the CLI (recommended)

Before running the CLI, check if uv is installed:

which uv || command -v uv

If uv is not found, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then source the shell profile (or restart the shell) so uvx is on PATH.

Then run the CLI:

curl -fsSL -o /tmp/cairn.whl \
  https://github.com/Percona-Lab/CAIRN/releases/latest/download/cairn_mcp-0.2.0-py3-none-any.whl
uvx --from /tmp/cairn.whl cairn init

The CLI prompts for:

1. Project type — API integration, Doc search, or Starter
2. Project name and description
3. Language — Python (FastMCP) or Node.js (@modelcontextprotocol/sdk)
4. Type-specific config:
   • API integration: service name, base URL, auth method, tool definitions
   • Doc search: stacks (groups of repos), keywords, refresh interval
   • Starter: nothing extra

Option 2: Guide the user through manual scaffolding

If the CLI isn't available, help the user create the project manually. Use the CAIRN repo templates as reference for the exact file contents.

---

After Scaffolding

Tell the user their next steps:

1. cd <project-dir> and review the generated code
2. API integration: Implement the TODO methods in connector.py / connector.js
3. Doc search: Customize source_registry.py keywords and _build_page_url() URL pattern
4. Starter: Add more @mcp.tool() functions
5. git init && git add -A && git commit -m "Initial scaffold from CAIRN"
6. Push to GitHub