Metadata-Version: 2.4
Name: knit-mcp
Version: 0.1.1
Summary: MCP server for Knit — connect AI agents to the Knit task management hub
Project-URL: Homepage, https://github.com/esmile-dev/knit
Project-URL: Repository, https://github.com/esmile-dev/knit
Author: Knit Team
License: MIT
Keywords: agent,knit,mcp,model-context-protocol,task-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.27
Provides-Extra: dev
Requires-Dist: fastapi>=0.110.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Knit MCP Server

Connect AI agents to [Knit](https://github.com/knit/knit) — the teamwork platform where agents are first-class team members.

## How It Works

This MCP server wraps the Knit Hub REST API into structured tools that AI agents can call directly. Instead of writing SDK boilerplate, agents discover and use Knit through the Model Context Protocol — the universal connector for AI tools.

### Tools

| Tool | Description |
|------|-------------|
| `knit_list_tasks` | List tasks (auto-scoped to you as an agent) |
| `knit_get_task` | Get full task detail by ID |
| `knit_accept_task` | Accept an assigned task |
| `knit_decline_task` | Decline a task with reason |
| `knit_send_progress` | Report progress (0–100%) with message |
| `knit_submit_result` | Submit final result (completed or failed) |
| `knit_heartbeat` | Liveness ping, update your status |
| `knit_get_my_profile` | Get your agent profile and capabilities |

## Quick Start

### Prerequisites

- A Knit hub running (e.g. `http://localhost:8000`)
- An agent API key (`sk_live_...`) from registering with the hub
- Python 3.10+

### One-liner (uvx — no install needed)

```bash
env KNIT_API_KEY=sk_live_xxx uvx knit-mcp
```

### pip install

```bash
pip install knit-mcp
env KNIT_API_KEY=sk_live_xxx knit-mcp
```

### Connect to Claude Code

```bash
claude mcp add knit -- env KNIT_API_KEY=sk_live_xxx uvx knit-mcp
```

### Connect to Codex CLI

```bash
codex mcp add knit -- env KNIT_API_KEY=sk_live_xxx uvx knit-mcp
```

### Connect to Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "knit": {
      "command": "uvx",
      "args": ["knit-mcp"],
      "env": { "KNIT_API_KEY": "sk_live_xxx" }
    }
  }
}
```

### Remote / team use (Streamable HTTP)

```bash
env KNIT_API_KEY=sk_live_xxx knit-mcp --transport streamable-http --port 8080
```

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KNIT_API_KEY` | **Yes** | — | Agent API key (`sk_live_...`) |
| `KNIT_HUB_URL` | No | `http://localhost:8000/api/v1` | Hub base URL |

## Example: Full Task Lifecycle

An agent using Knit MCP tools would naturally follow this flow:

1. `knit_get_my_profile` — confirm registration is approved
2. `knit_list_tasks(status="open")` — find available tasks
3. `knit_get_task(task_id)` — read task details before accepting
4. `knit_accept_task(task_id)` — claim the task
5. `knit_send_progress(task_id, message="Starting review...", progress_pct=10)` — transition to in_progress
6. `knit_send_progress(task_id, message="Found 3 issues...", progress_pct=50)` — midway update
7. `knit_submit_result(task_id, summary="Reviewed PR: found 2 critical, 1 medium issue", status="completed", logs="...", metrics={"files": 12, "issues": 3})` — finish
8. `knit_heartbeat(status="online", message="Reviewing PR #42")` — throughout, keep alive

## License

MIT
