Metadata-Version: 2.5
Name: projonatics-mcp
Version: 0.1.0
Summary: MCP server that lets Claude Code read projects, tasks and financials from a Projonatics instance
Project-URL: Homepage, https://github.com/Artiselite/projonatics
Project-URL: Repository, https://github.com/Artiselite/projonatics
Project-URL: Documentation, https://github.com/Artiselite/projonatics/blob/main/mcp/README.md
Author: Artiselite
Keywords: claude,claude-code,mcp,model-context-protocol,project-management,projonatics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.12
Description-Content-Type: text/markdown

# Projonatics MCP Server

Exposes the Projonatics API to Claude Code (or any MCP client) as read-only tools:
projects, tasks, milestones, payment milestones, financial summaries, dashboard and alerts.

It talks to a running Projonatics backend over HTTPS using a personal API token, so it
sees exactly what that user sees (role-based scoping applies).

## 1. Get an API token

In the app: open your profile menu (top right) → **Claude Code (MCP)** → **Generate token**. The key is shown once.

Or mint one on the server:

```bash
# production (docker)
docker compose -f docker-compose.prod.yml exec backend python manage.py drf_create_token you@company.com

# local
cd backend && python manage.py drf_create_token you@company.com
```

`GET /api/me/api-token/` reports whether a token exists; `DELETE` revokes it; `POST` again rotates it.

## 2. Register with Claude Code

Published on PyPI as [projonatics-mcp](https://pypi.org/project/projonatics-mcp/); `uvx` installs it on first run:

```bash
claude mcp add -s user projonatics \
  -e PROJONATICS_URL=https://<your-domain> \
  -e PROJONATICS_TOKEN=<token> \
  -- uvx projonatics-mcp
```

From a local clone (development): `-- uv run --directory /absolute/path/to/projonatics/mcp projonatics-mcp`.
To pick up a newer release: `uv cache clean projonatics-mcp` and restart Claude Code.

Check with `claude mcp get projonatics`. Re-run `claude mcp remove projonatics -s user` then `add` to change the URL or token.

## Tools

| Tool | What it returns |
|------|-----------------|
| `whoami` | User the token belongs to (id, email, role) |
| `list_clients` | All clients |
| `list_projects(client_id?)` | Projects visible to the user |
| `get_project(project_id)` | Full project detail |
| `list_milestones(project_id?)` | Work milestones |
| `list_tasks(project_id?, status?, assignee_id?, assigned_to_me?, ordering?)` | Tasks with filters |
| `get_task(task_id)` | One task |
| `get_project_financials(project_id)` | Revenue vs cost summary, payment milestones, cost breakdown |
| `list_payment_milestones(project_id?)` | Invoicing schedule |
| `get_dashboard` | Metrics, pulse, today's focus, pending payments |
| `get_alerts` | Overdue tasks, upcoming milestones, overdue payments, budget warnings, ready-to-invoice |
| `list_team_members` | Team roster |
| `estimate_cost(project_id, num_engineers, num_days)` | Cost estimate (admin) |

Admin-only endpoints (costs, margins, pending payments, estimates) return a 403 for
non-admin tokens; the error message says so.

## Development

```bash
cd mcp
uv sync
uv run pytest
```

Tests mock the HTTP transport; no backend needed.

## Releasing

Bump `version` in `pyproject.toml`, commit, then tag and push:

```bash
git tag mcp-v0.1.1 && git push origin mcp-v0.1.1
```

`.github/workflows/publish-mcp.yml` runs the tests, builds, and publishes to PyPI via trusted publishing.
