Metadata-Version: 2.4
Name: keshro-mcp
Version: 0.1.42
Summary: High-stakes engineering project execution for AI agents — MCP server
Project-URL: Homepage, https://keshro.com
Project-URL: Repository, https://github.com/jlewitt1/keshro-mcp
Project-URL: Documentation, https://keshro.com/developers
Author-email: Josh Lewittes <josh.lewittes@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,execution,mcp,model-context-protocol,planning
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.6.0
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# Keshro MCP

The intelligent execution layer for coding agents, exposed as an MCP server for high-stakes engineering projects.

```bash
pip install keshro-mcp
```

## When to use this vs the CLI

**Use the [CLI](https://github.com/jlewitt1/keshro-cli)** (`pip install keshro`) for the full experience: interactive clarifying questions, migration detection, parallel execution in isolated worktrees, git checkpoints, cross-task context routing, and cost tracking.

**Use MCP** if your agent platform speaks MCP and you want direct tool-call access to Keshro plans and tasks.

The CLI gives you more control. MCP is more flexible for custom integrations.

## Setup

Set your API token:

```bash
export KESHRO_API_TOKEN="ksh_pat_..."
```

Get one from [keshro.com/account](https://keshro.com/account?tab=api).

### Connect to your agent

MCP works with any agent that supports the protocol — Claude Code, Cline, Continue, Zed, and others.

**Claude Code** — add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "keshro": {
      "command": "keshro-mcp",
      "env": { "KESHRO_API_TOKEN": "ksh_pat_..." }
    }
  }
}
```

**Other MCP clients** — point your client at the `keshro-mcp` binary with `KESHRO_API_TOKEN` set in the environment. The server uses stdio transport.

## Available tools

| Tool | What it does |
|------|-------------|
| `preview_plan` | Run Keshro's pre-plan intake and clarifying-question preview |
| `generate_plan` | Generate a plan from a description using AI |
| `list_plans` | List all plans |
| `get_plan` | Get a plan with all tasks |
| `plan_status` | Progress summary (task counts, enrichment sources) |
| `next_task` | Get the next actionable task |
| `create_plan` | Create a plan manually |
| `start_task` | Mark a task as in progress |
| `complete_task` | Mark a task as done |
| `block_task` | Mark a task as blocked |
| `unblock_task` | Clear a blocker |
| `append_task_note` | Add a note to a task |
| `add_task_artifact` | Attach an artifact link |
| `record_decision` | Log a decision with context, choice, and reasoning |
| `edit_task` | Edit task title or description |
| `push_to_tracker` | Push tasks to Linear, Jira, or GitHub as issues |
| `sync_pull` | Pull status updates from connected issue tracker |
| `export_project` | Export project data |

## Current parity notes

MCP now supports the newer task controls exposed in the web product:

- explicit `depends_on` task dependencies
- `parallelizable` task scheduling hints
- per-task `executor` selection
- generic issue linking via `issue_id`, plus external issue fields
- pre-plan intake via `preview_plan`

It still remains thinner than the CLI for actual execution orchestration. The CLI owns parallel local worktrees, git checkpoints, richer execution transcripts, and the direct `keshro continue` runtime loop.

## License

MIT
# Releases

Publish the MCP package with one GitHub Actions run after you bump `pyproject.toml`:

```bash
gh workflow run "Publish MCP"
```

That workflow reads the package version from `pyproject.toml`, publishes the package to PyPI, then creates the matching `vX.Y.Z` GitHub release automatically.
