Metadata-Version: 2.4
Name: codens-mcp
Version: 0.7.3
Summary: Unified MCP server for Codens family — Red (auto-fix), Blue (QA), Green (PRD), Auth, Purple (orchestration). All-in-one, no external purple-codens-mcp dependency.
Project-URL: Homepage, https://github.com/Corevice/purple-codens/tree/main/codens-mcp
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/codens-mcp/CHANGELOG.md
Author-email: Corevice <engineering@corevice.com>
License: MIT
License-File: LICENSE
Keywords: agent,auto-fix,automation,claude,codens,mcp,prd,qa,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
Requires-Dist: pytest-asyncio>=0.23.0
Requires-Dist: pytest>=8.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

# codens-mcp

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

Unified MCP server for the **Codens family** — lets Claude Code and other AI agents operate all Codens services through a single package.

Includes all 16 **Purple** tools (re-exported from `purple-codens-mcp`) plus new tools for **Red** (auto-fix), **Blue** (QA), **Green** (PRD), and **Auth Codens**.

> 📖 **Full agent reference**: [help.codens.ai](https://help.codens.ai/) (JA) / [help.codens.ai/en](https://help.codens.ai/en/) (EN). The help page is the canonical, machine-readable reference for using Codens from any AI agent — covers Quick Start, Device Code Flow login, four practical use cases, all 30 tools, the error envelope, 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 codens-mcp
```

## Quick Start (Claude Code)

### 1. Install

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

### 2. Register the MCP server

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

```json
{
  "mcpServers": {
    "codens": {
      "command": "codens-mcp",
      "args": []
    }
  }
}
```

Running `codens-mcp` with no arguments starts the MCP server (default
`serve` subcommand) — same behavior as before.

### 3. Log in (once, via Device Code Flow)

```bash
codens-mcp login
```

The CLI prints a verification URL and a short user code:

```
============================================================
  Device Authorization Required
============================================================

  1. Open this URL on any device:
     https://auth.codens.ai/device

  2. Enter this code when prompted:
     ABCD-1234

  Waiting for authorization (expires in 15 minutes)...
============================================================
```

Open the URL on any browser, paste the code, and approve. The CLI
detects the approval, fetches your JWT, and stores it at
`~/.purple-codens/credentials.json` (mode `0600`). The token is
accepted by all Codens family backends (Red / Blue / Green / Purple /
Auth), so subsequent tool calls require no further login.

```bash
# Verify
codens-mcp whoami
# → Email: you@example.com
#   User ID: ...
#   Organization: ...
```

Use `--auth-url` / `--api-url` to point the login at non-default
environments (e.g. `--auth-url https://api.dev.auth.codens.ai`).

> Inside Claude Code you can also call the MCP `purple_login` tool
> instead — both flows produce the same credential file.

## Available Tools (31 total)

### Auth / Session (Purple)
| Tool | Description |
|------|-------------|
| `purple_login` | Log in via browser OAuth, device code, or email+password |
| `purple_whoami` | Show current authenticated user and organization |

### Project Setup (Purple)
| Tool | Description |
|------|-------------|
| `purple_analyze_repo` | Scan local repo and return structured analysis |
| `purple_list_projects` | List all projects in the organization |
| `purple_init_project` | Full project setup: create → link repo → import instructions |

### Repository (Purple)
| Tool | Description |
|------|-------------|
| `purple_add_repository` | Link a GitHub repository to a project |
| `purple_list_repositories` | List repositories linked to a project |

### Instruction Files (Purple)
| Tool | Description |
|------|-------------|
| `purple_import_instructions` | Import CLAUDE.md + .claude/rules/ from GitHub |
| `purple_list_instructions` | List instruction files for a project |
| `purple_sync_instructions` | Diff local vs remote, update changed files |

### Workflow & Runs (Purple)
| Tool | Description |
|------|-------------|
| `purple_create_workflow` | Create a new workflow |
| `purple_get_run_status` | Get current status of a workflow run |
| `purple_list_runs` | List workflow runs (filter by project/status) |
| `purple_cancel_run` | Cancel a running workflow |
| `purple_inject_message` | Inject a message into a heartbeat run |
| `purple_subscribe_run_events` | Stream SSE events for a workflow run |

### Log Retrieval (Purple)
| Tool | Args | Description |
|------|------|-------------|
| `purple_get_run_logs` | `api_url`, `organization_id`, `run_id` | Get VPS job logs for a workflow run — returns `jobs[]` each with a presigned `log_url` (valid 1 hour) |
| `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 (valid 1 hour) |

#### `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"
    }
  ]
}
```

#### `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
```

### Red Codens — Auto-Fix
| Tool | Description |
|------|-------------|
| `red_create_bug_report` | Create a bug report (agent endpoint) |
| `red_get_bug_report` | Get a bug report by ID |
| `red_analyze_bug_report` | Trigger AI analysis for a bug report |
| `red_submit_bug_fix_plan_to_purple` | Submit a fix plan to Purple for execution |

### Blue Codens — QA Automation
| Tool | Description |
|------|-------------|
| `blue_list_e2e_tests` | List E2E tests |
| `blue_generate_e2e_test` | Generate an E2E test from a natural-language requirement |
| `blue_run_e2e_test` | Trigger a run for an existing E2E test |
| `blue_get_e2e_test_results` | Get results for an E2E test (latest run) |

### Green Codens — PRD Management
| Tool | Description |
|------|-------------|
| `green_create_consultation_with_message` | Start a consultation and send the first message |
| `green_send_consultation_message` | Send a message in an existing consultation |
| `green_convert_consultation_to_prd` | Convert a consultation into a PRD |
| `green_create_kickoff` | Create a Kickoff in Green Codens |

### Auth Codens
| Tool | Description |
|------|-------------|
| `auth_agent_signup` | Issue capability_token via existing user's API key |
| `auth_get_pricing` | Public pricing.json (no auth required) |

### Cross-product
| Tool | Description |
|------|-------------|
| `codens_register_project_unified` | Register the same GitHub repo as a project across Purple/Red/Blue/Green in one call (best-effort, returns per-product IDs and any errors) |

## Changelog

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

## License

MIT — Copyright 2026 Corevice Inc.
