thinker-mcp

MCP server for the 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)

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

Via uvx (no checkout required)

uvx thinker-mcp

---

Configuration

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

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):

{
  "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:

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

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

# 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/