# thinker-mcp

MCP server for the [thinker-ci](https://github.com/thinker-ci) platform.  Exposes tickets, CI/CD pipelines, project-management data, and AI-agent sessions as MCP tools and resources so that Claude Code (or any other MCP-capable client) can interact with the platform directly from the assistant.

---

## Architecture

```
Claude Code / Cursor / other MCP client
           │  stdio / SSE
           ▼
      thinker-mcp          ← this repo
     ┌──────────────────────────────────┐
     │  tools/tickets.py  (file-system) │─── reads/writes thinker-blueprint/
     │  tools/pipelines.py              │─── thinker-console REST API
     │  tools/pm.py                     │─── thinker-console REST API
     │  tools/agents.py                 │─── thinker-agent REST API
     │  resources/schema.py             │─── thinker-console /api/schema/
     │  resources/docs.py               │─── thinker-blueprint/ (local)
     └──────────────────────────────────┘
           │                      │
    thinker-console          thinker-agent
    (Django REST API)        (LLM agent API)
           │
    thinker-blueprint
    (git repo on disk)
```

**thinker-console** is the central Django application that owns projects, pipelines, runs, PM objects (epics, stories, tasks, sprints, milestones), and user/tenant data.

**thinker-agent** is a lightweight FastAPI service that manages stateful LLM sessions.  It proxies requests to Anthropic, OpenAI, Google, and AWS Bedrock.

**thinker-blueprint** is a git repository of Markdown files that serves as the project's file-system ticketing system.  The `tickets/` tree is readable and writable by thinker-mcp without going through an API.

---

## Installation

### From source (development)

```bash
git clone git@github.com:thinker-ci/thinker-mcp.git
cd thinker-mcp
pip install -e .
```

### Via uvx (no checkout required)

```bash
uvx thinker-mcp
```

---

## Configuration

Copy `.env.example` to `.env` and fill in the values:

```bash
cp .env.example .env
$EDITOR .env
```

| Variable | Default | Description |
|----------|---------|-------------|
| `THINKER_CONSOLE_URL` | `http://localhost:8000` | Base URL of the thinker-console Django API |
| `THINKER_CONSOLE_TOKEN` | _(required)_ | API token for authenticating to thinker-console (`Token <value>`) |
| `THINKER_AGENT_URL` | `http://localhost:8080` | Base URL of the thinker-agent FastAPI service |
| `THINKER_AGENT_TOKEN` | _(required)_ | Bearer token for authenticating to thinker-agent |
| `THINKER_BLUEPRINT_PATH` | `/data/thinker-blueprint` | Absolute path to a local checkout of thinker-blueprint |

---

## Tools

### Ticket tools (file-system)

These tools read from and write to the `tickets/` tree inside a local `thinker-blueprint` checkout.  No network calls are made.

| Tool | Parameters | Description |
|------|-----------|-------------|
| `tickets_list` | `status`, `type`, `sprint`, `assignee` | List tickets with optional filters |
| `ticket_get` | `id` | Get full markdown content of a ticket (e.g. `STORY-003`) |
| `ticket_update_status` | `id`, `status` | Update the `status:` frontmatter field |
| `ticket_create` | `type`, `title`, `description`, `epic_id`, `priority`, `sprint` | Create a new ticket file |

### Pipeline tools (thinker-console)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `pipelines_list` | `project_slug` | List pipelines for a project |
| `pipeline_trigger` | `pipeline_id`, `branch`, `commit_sha?` | Trigger a pipeline run |
| `run_get` | `run_id` | Get status and metadata for a run |
| `run_logs` | `job_id` | Fetch raw logs from a job |
| `run_cancel` | `run_id` | Cancel a running pipeline run |
| `runners_list` | — | List all CI runners and their status |

### Project-management tools (thinker-console)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `epics_list` | `status?`, `milestone?` | List epics |
| `stories_list` | `epic_id?`, `sprint_id?`, `status?` | List stories |
| `tasks_list` | `story_id?`, `assignee?`, `status?` | List tasks |
| `story_update` | `story_id`, `status?`, `story_points?` | Update a story |
| `task_create` | `title`, `story_id`, `task_type?`, `estimate?` | Create a task |
| `sprint_board` | — | Current sprint kanban board |
| `sprints_list` | — | List all sprints |
| `milestones_list` | — | List all milestones |

### Agent tools (thinker-agent)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `agent_session_create` | `provider`, `model_id`, `system_prompt?` | Create a new LLM session |
| `agent_message_send` | `session_id`, `message` | Send a message; returns the assistant response |
| `agent_sessions_list` | — | List all active sessions |

---

## Resources

| URI | MIME type | Description |
|-----|-----------|-------------|
| `thinker://openapi/schema` | `application/json` | Live OpenAPI 3.x schema from thinker-console |
| `thinker://docs/architecture` | `text/markdown` | Concatenated `architecture/*.md` from thinker-blueprint |
| `thinker://tickets/<stem>` | `text/markdown` | Individual ticket file (e.g. `thinker://tickets/STORY-003-tenant-model`) |

---

## Using with Claude Code

Add to your project's `.claude.json` (or `~/.claude.json` for global access):

```json
{
  "mcpServers": {
    "thinker": {
      "command": "thinker-mcp",
      "env": {
        "THINKER_CONSOLE_URL": "https://console.thinker.ci",
        "THINKER_CONSOLE_TOKEN": "your-token-here",
        "THINKER_AGENT_URL": "https://agent.thinker.ci",
        "THINKER_AGENT_TOKEN": "your-agent-token-here",
        "THINKER_BLUEPRINT_PATH": "/home/you/thinker-blueprint"
      }
    }
  }
}
```

Or use a `.env` file in your working directory instead of inline `env` keys.

Restart Claude Code after editing the config.  Run `/mcp` to verify the server is connected and tools are listed.

---

## Using with other MCP clients

Any client that supports the MCP stdio transport can connect by spawning:

```bash
thinker-mcp
```

The server reads `STDIN` and writes `STDOUT` using the JSON-RPC framing defined by the MCP protocol.  Set the environment variables above before launching.

---

## Running in Docker

```bash
docker build -t thinker-mcp .
docker run --rm -i \
  -e THINKER_CONSOLE_URL=http://console:8000 \
  -e THINKER_CONSOLE_TOKEN=secret \
  -e THINKER_AGENT_URL=http://agent:8080 \
  -e THINKER_AGENT_TOKEN=secret \
  -v /data/thinker-blueprint:/data/thinker-blueprint:ro \
  thinker-mcp
```

---

## Development

```bash
# Install in editable mode with dev extras (add [dev] if you add them to pyproject.toml)
pip install -e .

# Lint
ruff check src/

# Format
ruff format src/
```