Purple Codens MCP Server

⚠️ DEPRECATED: purple-codens-mcp is deprecated as of 0.3.2. MCP support for the Codens family has been consolidated into a single package, codens-mcp. Please migrate:

pip uninstall purple-codens-mcp
pip install codens-mcp

See help.codens.ai for the migration guide. This package will receive no further feature work and only critical fixes, if any.

MCP (Model Context Protocol) server for Purple Codens — AI Development Orchestration.

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

📖 Full agent reference: help.codens.ai (JA) / 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 or the full plain-text dump at llms-full.txt.

Installation

pip install purple-codens-mcp

Or from source:

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

Claude Code Integration

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

{
  "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

{
  "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

{
  "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

# 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

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.