mcp-project 1.0.0

# Project MCP Server

[![Crates.io](https://img.shields.io/crates/v/mcp-project.svg)](https://crates.io/crates/mcp-project)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![ADK-Rust Enterprise](https://img.shields.io/badge/ADK--Rust-Enterprise-purple.svg)](https://enterprise.adk-rust.com)
[![Registry Ready](https://img.shields.io/badge/ADK_Registry-Ready-green.svg)](https://www.zavora.ai)

A fully-featured project-management layer for [ADK-Rust Enterprise](https://enterprise.adk-rust.com) agents. 27 MCP tools covering projects, work items, sprints, milestones, dependencies, time tracking, and reporting — the building blocks for planning, standup, and delivery-tracking agents.

## What It Does

Everything an agent needs to run a project the way a team does in Jira / Linear / Asana:

- **Projects** with a KEY (the task-id prefix, e.g. `APOLLO-12`), lead, members, and status lifecycle
- **Work items** — epics, stories, tasks, bugs, subtasks — with a full workflow, priority, estimates, labels, assignees, comments, and due dates
- **Dependencies** — `blocked_by` / `blocks` / `relates_to`, with **cycle detection** and **blocker-aware transitions** (a task can't start/finish while its blockers are open)
- **Sprints / iterations** with goals and burndown inputs
- **Milestones** with due dates and status
- **Time tracking** — log hours against tasks
- **Reporting** — project progress, sprint report, **critical path**, and per-assignee workload

## Architecture

<p align="center">
  <img src="https://raw.githubusercontent.com/zavora-ai/mcp-project/main/docs/architecture.svg" alt="Project MCP Architecture" width="750"/>
</p>

## Task Workflow

```
backlog → todo → in_progress → in_review → done
                      ↓             ↑
                   blocked ─────────┘        (any → cancelled; done → in_progress to reopen)
```

Transitions are validated. Moving a task to `in_progress`/`in_review`/`done` is refused while any `blocked_by` task is unfinished.

## Tools (27)

### Projects (5)
`create_project` · `get_project` · `list_projects` · `set_project_status` · `add_member`

### Tasks / Work Items (10)
`create_task` · `get_task` · `search_tasks` · `update_task` · `transition_task` · `assign_task` · `set_labels` · `add_dependency` · `add_comment` · `log_time`

### Sprints (4)
`create_sprint` · `set_sprint_status` · `assign_to_sprint` · `list_sprints`

### Milestones (4)
`create_milestone` · `set_milestone_status` · `assign_to_milestone` · `list_milestones`

### Reporting (4)
| Tool | What It Does |
|------|-------------|
| `project_progress` | Status counts, completion %, story points done/total, hours logged |
| `sprint_report` | Scope, completed, points completed/remaining (burndown inputs) |
| `critical_path` | Longest `blocked_by` chain — a schedule-risk proxy |
| `workload` | Open/done tasks and points per assignee |

## Example

```
> create_project(key: "ZED", name: "Zephyr", lead: "dana", members: ["dana","evan"])
  → PRJ-1004

> create_task(project_id: "PRJ-1004", task_type: "story", title: "API gateway",
              reporter: "dana", assignee: "evan", estimate: 8)   → ZED-1
> create_task(project_id: "PRJ-1004", title: "Provision infra", reporter: "dana", estimate: 5)  → ZED-2

> add_dependency(task_id: "ZED-1", dep_type: "blocked_by", other_id: "ZED-2")
> transition_task(id: "ZED-1", status: "in_progress")
  → Error: Blocked by unfinished task(s): ZED-2      ← blocker-aware

> transition_task(id: "ZED-2", status: "done")  (after todo→in_progress)
> transition_task(id: "ZED-1", status: "in_progress")   → in_progress ✓

> project_progress(project_id: "PRJ-1004")   → 50% complete
> critical_path(project_id: "PRJ-1004")      → length 2, path [ZED-2, ZED-1]
```

## Installation

### 1. Build

```bash
git clone https://github.com/zavora-ai/mcp-project
cd mcp-project
cargo build --release
```

### 2. Add to your MCP client

**Claude Desktop / Kiro / Cursor / Windsurf:**
```json
{
  "mcpServers": {
    "project": {
      "command": "/path/to/mcp-project"
    }
  }
}
```

### 3. Use it

```
> list_projects()
> search_tasks(project_id: "PRJ-1001", status: "in_progress")
> sprint_report(id: "SPR-1002")
```

## Governance & Data Handling

- **Gated writes** — status changes (`set_project_status`, `transition_task`, `set_sprint_status`, `set_milestone_status`) require approval in production; reads/reports are `read_only`.
- **Validated workflow** — invalid transitions and dependency cycles are rejected.
- **Integration scaffold** — the in-memory store is for development; back it with a durable store and bind actors to authenticated identities in production.

## MCP Server Manifest

```toml
server_id = "mcp_project"
display_name = "Project Management"
version = "1.0.0"
domain = "operations"
risk_level = "medium"
writes_allowed = "gated"
transports = ["stdio"]
```

## Contributors

<!-- ALL-CONTRIBUTORS-LIST:START -->
| [<img src="https://github.com/jkmaina.png" width="80px;" alt=""/><br /><sub><b>James Karanja Maina</b></sub>](https://github.com/jkmaina) |
|:---:|
<!-- ALL-CONTRIBUTORS-LIST:END -->

## License

Apache-2.0 — see [LICENSE](LICENSE) for details.

---

Part of the [ADK-Rust Enterprise](https://enterprise.adk-rust.com) MCP server ecosystem.

## Registry Compliance

This server implements the [ADK MCP SDK](https://crates.io/crates/adk-mcp-sdk) contract:

- **HealthCheck** — async health probe for registry monitoring
- **mcp-server.toml** — manifest declaring tools, risk classes, and approval gates
- **Structured tracing** — `RUST_LOG` env-filter for observability