MCP 服务器

@letretro/mcp

Enables AI coding tools to access LetRetro retrospectives, boards, cards, and team data through MCP.

README

<div align="center"> <img src="./public/logo.svg" alt="LetRetro" width="120" /> <br/> <br/> <h1>@letretro/mcp</h1> <p><strong>LetRetro MCP — Connect your AI coding tools to LetRetro retrospectives.</strong></p>

What is this?

@letretro/mcp is the official Model Context Protocol package for LetRetro. It gives AI coding assistants direct access to your LetRetro workspace — boards, cards, retrospectives, and team data.

It runs in two modes:

Mode	What it does
`install`	Interactive CLI wizard that auto-configures your MCP clients
server (default)	Local MCP stdio server using the official MCP SDK — forwards requests to `mcp.letretro.com`

One install command, zero manual JSON editing.

Quick start

npx @letretro/mcp install

You'll be prompted for your LetRetro API key. The installer detects your installed MCP clients and writes the configuration — you pick which ones to set up.

  ╔══════════════════════════════════╗
  ║     LetRetro MCP Installer       ║
  ╚══════════════════════════════════╝

  Enter your LetRetro API Key: ••••••

  Detected clients:
    ✓ Claude Desktop
    ✓ Cursor
    ✓ VS Code
    ✓ OpenAI Codex CLI
    ✓ OpenCode
    ✓ Antigravity
    ✓ Hermes
    ✓ OpenClaw

  (Use space to select, enter to confirm)
  ✔ Select clients to configure:

  ✓ Claude Desktop: Updated ~/Library/Application Support/Claude/claude_desktop_config.json
  ✓ Cursor: Created ~/.cursor/mcp.json

  ╔══════════════════════════════════╗
  ║     LetRetro MCP Installed        ║
  ╚══════════════════════════════════╝

  Restart your MCP clients to start using
  LetRetro tools.

What gets configured

The installer adds a letretro server entry to your client's MCP config:

{
  "mcpServers": {
    "letretro": {
      "command": "npx",
      "args": ["-y", "@letretro/mcp"],
      "env": {
        "LETRETRO_API_KEY": "lr_..."
      }
    }
  }
}

Restart your AI coding tool and LetRetro tools are automatically available.

Supported clients

The installer auto-detects these clients and writes the correct config for each:

Client	Auto-detect	Config file written	Format
Claude Desktop	✅ macOS/Linux	`claude_desktop_config.json`	JSON
Cursor	✅	`~/.cursor/mcp.json`	JSON
VS Code	✅ binary + config	`.vscode/mcp.json`	JSON
OpenAI Codex CLI	✅	`~/.codex/config.toml`	TOML
OpenCode	✅	`~/.config/opencode/opencode.json`	JSON
Antigravity	✅	`~/.gemini/config/mcp_config.json`	JSON
Hermes	✅	`~/.hermes/config.yaml`	YAML
OpenClaw	✅	`~/.openclaw/openclaw.json`	JSON
Windsurf	✅ config check	`~/.codeium/windsurf/mcp_config.json`	JSON
Continue	✅	`~/.continue/config.json`	JSON

Don't see your client? Open an issue.

How it works

AI Assistant                npx @letretro/mcp              mcp.letretro.com
     │                            │                              │
     │  MCP JSON-RPC over stdio   │                              │
     │  (initialize, tools/list,  │                              │
     │   tools/call, ...)         │                              │
     │──────────────────────────> │                              │
     │                            │  HTTP POST (Bearer token)    │
     │                            │  (forwarded JSON-RPC)        │
     │                            │ ────────────────────────────>│
     │                            │                              │
     │                            │  JSON-RPC response           │
     │                            │ <────────────────────────────│
     │  MCP JSON-RPC response     │                              │
     │ <──────────────────────────│                              │

The local process is a proper MCP stdio server built with the official MCP SDK. It:

Handles the full MCP handshake (initialize, ping, notifications/*)
Implements tools/list with a cached response from the remote server
Forwards tools/call requests to mcp.letretro.com and returns results
Supports graceful shutdown via SIGTERM/SIGINT
Reads LETRETRO_API_KEY and an optional LETRETRO_MCP_URL override from the environment

All MCP tools, resources, and prompts are implemented server-side on mcp.letretro.com, so you get updates instantly — no package upgrade needed.

Manual setup

If you prefer to configure clients manually instead of using the installer, add the following to your client's MCP config file.

Claude Desktop / Cursor / Antigravity / OpenClaw / Windsurf / Continue:

{
  "mcpServers": {
    "letretro": {
      "command": "npx",
      "args": ["-y", "@letretro/mcp"],
      "env": {
        "LETRETRO_API_KEY": "your_key_here"
      }
    }
  }
}

VS Code:

{
  "servers": {
    "letretro": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@letretro/mcp"],
      "env": {
        "LETRETRO_API_KEY": "your_key_here"
      }
    }
  }
}

OpenCode:

{
  "mcp": {
    "letretro": {
      "type": "local",
      "command": ["npx", "-y", "@letretro/mcp"],
      "enabled": true,
      "environment": {
        "LETRETRO_API_KEY": "your_key_here"
      }
    }
  }
}

OpenAI Codex CLI:

[mcp_servers.letretro]
command = "npx"
args = ["-y", "@letretro/mcp"]

[mcp_servers.letretro.env]
LETRETRO_API_KEY = "your_key_here"

Hermes:

mcp_servers:
  letretro:
    command: "npx"
    args:
      - "-y"
      - "@letretro/mcp"
    env:
      LETRETRO_API_KEY: "your_key_here"

Environment variables

Variable	Default	Description
`LETRETRO_API_KEY`	—	Your LetRetro API key (required)
`LETRETRO_MCP_URL`	`https://mcp.letretro.com`	Override the remote MCP server URL (for testing)
`LETRETRO_VALIDATE_URL`	`https://mcp.letretro.com`	URL used for API key validation during install

Development

git clone https://github.com/LetRetroHQ/mcp-cli.git
cd letretro-mcp/mcp-npm
pnpm install
pnpm dev          # watch mode
pnpm build        # production build
pnpm typecheck    # type checking
pnpm test         # run tests

Project structure

src/
├── index.ts           # Entry point — routes to install or server mode
├── install.ts         # Interactive installer (prompt → detect → configure)
├── server.ts          # MCP stdio server (MCP SDK) — forwards to mcp.letretro.com
├── clients/
│   ├── index.ts       # Client registry and detection helpers
│   ├── claude.ts      # Claude Desktop
│   ├── cursor.ts      # Cursor
│   ├── vscode.ts      # VS Code
│   ├── codex.ts       # OpenAI Codex CLI (TOML config)
│   ├── opencode.ts    # OpenCode
│   ├── antigravity.ts # Google Antigravity
│   ├── hermes.ts      # Hermes Agent (YAML config)
│   ├── openclaw.ts    # OpenClaw
│   ├── windsurf.ts    # Windsurf
│   └── continue.ts    # Continue
└── utils/
    ├── paths.ts       # OS-aware config file paths
    ├── toml.ts        # TOML serializer for Codex config
    └── yaml.ts        # YAML serializer for Hermes config

Contributing

Contributions are welcome! Whether it's adding support for a new MCP client, improving the installer, or fixing a bug:

Fork the repo
Create a feature branch (git checkout -b feat/my-feature)
Commit your changes (git commit -am 'feat: add support for...')
Push to the branch (git push origin feat/my-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

MIT © LetRetro

<div align="center"> <sub>Built by the LetRetro team</sub> </div>