Metadata-Version: 2.4
Name: purple-codens-mcp
Version: 0.3.0
Summary: MCP server for Purple Codens — AI Development Orchestration. Lets coding agents (Claude Code etc.) initialize projects, link repositories, and manage workflows.
Project-URL: Homepage, https://github.com/Corevice/purple-codens
Project-URL: Repository, https://github.com/Corevice/purple-codens
Project-URL: Issues, https://github.com/Corevice/purple-codens/issues
Project-URL: Changelog, https://github.com/Corevice/purple-codens/blob/main/purple-codens-mcp/CHANGELOG.md
Author-email: Corevice <engineering@corevice.com>
License: MIT
License-File: LICENSE
Keywords: agent,automation,claude,codens,mcp,workflow
Classifier: Development Status :: 4 - Beta
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 :: Python Modules
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Purple Codens MCP Server

[![PyPI version](https://img.shields.io/pypi/v/purple-codens-mcp.svg)](https://pypi.org/project/purple-codens-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/purple-codens-mcp.svg)](https://pypi.org/project/purple-codens-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for [Purple Codens](https://purple.codens.ai) — AI Development Orchestration.

Install this package to manage Purple Codens projects from any repository using Claude Code.

> 📖 **Full agent reference**: [help.codens.ai](https://help.codens.ai/) (JA) / [help.codens.ai/en](https://help.codens.ai/en/) (EN). Covers Quick Start, Device Code Flow login (incl. the `purple-codens-mcp login` CLI as a reliable workaround when the agent-side `codens_login` hangs), four practical use cases, all 30 tools, error semantics, pricing, and troubleshooting. AI crawlers can ingest [`llms.txt`](https://help.codens.ai/llms.txt) or the full plain-text dump at [`llms-full.txt`](https://help.codens.ai/llms-full.txt).

## Installation

```bash
pip install purple-codens-mcp
```

Or from source:

```bash
cd purple-codens/purple-codens-mcp
pip install -e .
```

## Claude Code Integration

Add to `.claude/settings.json` in your repository:

```json
{
  "mcpServers": {
    "purple-codens": {
      "command": "purple-codens-mcp",
      "args": ["--api-url", "https://api.purple.codens.ai"]
    }
  }
}
```

## Available Tools

### Auth

| Tool | Description |
|------|-------------|
| `purple_login(api_url, email, password)` | Log in and store JWT in `~/.purple-codens/credentials.json` |
| `purple_whoami(api_url)` | Return current user and organization info |

### Project Setup

| Tool | Description |
|------|-------------|
| `purple_analyze_repo(cwd?)` | Scan local repo: detect CLAUDE.md, rules, test commands, CI workflows, git remote |
| `purple_init_project(api_url, name, ...)` | Create project, link repo, import instructions — all in one call |
| `purple_list_projects(api_url)` | List all projects in the organization |

### Repository

| Tool | Description |
|------|-------------|
| `purple_add_repository(api_url, project_id, github_owner, github_repo, branch, workflow_type)` | Link a GitHub repository to a project |
| `purple_list_repositories(api_url, project_id)` | List repositories linked to a project |

### Instruction Files

| Tool | Description |
|------|-------------|
| `purple_import_instructions(api_url, project_id, repository_id)` | Pull CLAUDE.md + .claude/rules/ from GitHub into Purple Codens |
| `purple_list_instructions(api_url, project_id)` | List instruction files for a project |
| `purple_sync_instructions(api_url, project_id, cwd?)` | Diff local files with Purple Codens and update changed ones |

### Workflow & Run Management

| Tool | Description |
|------|-------------|
| `purple_create_workflow(api_url, organization_id, project_id, name, spec)` | Create a new workflow |
| `purple_get_run_status(api_url, organization_id, run_id)` | Get current status of a workflow run |
| `purple_subscribe_run_events(api_url, run_id, max_events?, timeout_seconds?)` | Subscribe to SSE events for a run (org_id resolved from auth token) |
| `purple_inject_message(api_url, organization_id, project_id, run_id, message)` | Inject an instruction into a heartbeat run |
| `purple_list_runs(api_url, organization_id, project_id?, status?)` | List workflow runs scoped to org, optionally filtered |
| `purple_cancel_run(api_url, organization_id, run_id, reason?)` | Cancel a running workflow |

### Log Retrieval

| Tool | Args | Description |
|------|------|-------------|
| `purple_get_run_logs` | `api_url`, `organization_id`, `run_id` | Get VPS job logs for a workflow run |
| `purple_get_task_log_url` | `api_url`, `organization_id`, `project_id`, `task_id` | Get S3 presigned log URL for a task's latest Claude Code job |

#### `purple_get_run_logs` — response shape

```json
{
  "status": "success",
  "run_id": "<run_id>",
  "total": 2,
  "jobs": [
    {
      "job_id": "job_abc",
      "status": "completed",
      "log_url": "https://s3.amazonaws.com/...?X-Amz-Expires=3600&...",
      "started_at": "2026-05-14T10:00:00Z",
      "finished_at": "2026-05-14T10:05:00Z"
    }
  ]
}
```

Each `log_url` is an S3 presigned URL **valid for 1 hour**.

#### `purple_get_task_log_url` — response shape

```json
{
  "status": "success",
  "log_url": "https://s3.amazonaws.com/...?X-Amz-Expires=3600&...",
  "note": "Presigned URL is valid for 1 hour."
}
```

When no log exists yet, `log_url` is `null` (status remains `"success"`).

#### Example: inspect a failed run

```python
# 1. Check run status
status = purple_get_run_status(api_url=URL, organization_id=ORG, run_id=RUN)
# → {"status": "success", "run": {"status": "failed", ...}}

# 2. Fetch all job logs for that run
logs = purple_get_run_logs(api_url=URL, organization_id=ORG, run_id=RUN)
# → {"status": "success", "total": 1, "jobs": [{"log_url": "https://..."}]}

# 3. Download the log (URL valid for 1 hour)
import httpx
log_text = httpx.get(logs["jobs"][0]["log_url"]).text
```

## Typical Workflow

```
# In Claude Code, after adding the MCP server to settings.json:

1. purple_login       → authenticate
2. purple_analyze_repo → inspect current repo
3. purple_init_project → create project + link repo + import instructions
4. purple_list_projects → confirm project created
5. purple_sync_instructions → keep instructions in sync as CLAUDE.md evolves
```

## Credential Storage

JWT tokens are stored in `~/.purple-codens/credentials.json` with `0600` permissions (owner read/write only). Tokens are keyed by `api_url` so multiple Purple Codens instances are supported.

On 401 responses, credentials are automatically cleared and an `AuthenticationError` is raised prompting re-login.

## Development

```bash
cd purple-codens/purple-codens-mcp

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=term
```

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).
