@codmir/mcp

Codmir MCP Server

AI-powered task execution, ticket management, and agent workflows for Windsurf, Cursor, Claude Desktop, and the Codmir CLI.

Features

• To-Do List - View and manage actionable tickets from your AI assistant
• Execute Tasks - Run AI-powered code tasks (bug fixes, features, refactors)
• Sprint Management - View and manage sprint tasks
• Create Tickets - Capture bugs and features from conversations
• Store Context - Save important discussions as documentation
• Error Debugging - Look up and debug production errors (Overseer integration)
• SDK Reference - Get API reference and generate code from your editor
• Project Overview - Get project context, tech stack, and activity

Quick start

# 1. Authenticate
codmir login

# 2. Add to your editor config (see below)
# 3. Ask your AI: "list my to-do items"

Editor setup

Windsurf

Add to .windsurf/mcp.json:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

VS Code

Install the Codmir extension. The To-Do List sidebar connects to the same API automatically.

Authentication

# Interactive login (recommended)
codmir login

# Or set environment variables
export CODMIR_API_TOKEN="your-token"
export CODMIR_USER_ID="your-user-id"
export CODMIR_API_URL="https://codmir.com"  # optional

Credentials are stored in ~/.codmir/credentials.json.

Available tools

Tool	Description
list_todo	List actionable to-do tickets (open, in_progress, review)
update_todo_status	Mark a ticket as done, in-progress, or reopen
execute_task	Run an AI-powered code task
get_sprint_tasks	Get tasks for current/specified sprint
create_ticket	Create a new ticket
list_project_tasks	List all project tasks
check_task_status	Check running task status
get_project_context	Get project overview and tech stack
store_conversation	Save conversation as documentation
lookup_error	Look up a production error by any reference
list_recent_errors	List recent production errors
get_error_context	Enriched error context for AI debugging
get_sdk_reference	SDK API reference for a topic
generate_sdk_code	Generate ready-to-use SDK code
create_organization	Create a new workspace
create_project	Create a project within an organization
get_workspace_status	Check workspace setup status

Usage examples

To-do list

You: What's on my to-do list?

AI: [Uses list_todo] → Shows actionable tickets sorted by priority

You: Mark TKT-42 as done

AI: [Uses update_todo_status] → Updated ticket status to done

Execute a task

You: Fix the authentication bug in src/auth/login.ts

AI: [Uses execute_task] → Queues task for AI agent → Returns execution ID

Create a ticket

You: Create a ticket for the performance issue we just discussed

AI: [Uses create_ticket] → Creates ticket with context → Returns ticket ID

Debug an error

You: What's happening with error err_abc123?

AI: [Uses lookup_error + get_error_context]
→ Shows stack trace, breadcrumbs, and suggested files to investigate

CLI usage

# List to-do items
codmir mcp todo
codmir mcp todo --priority high
codmir mcp todo --status in_progress

# Update ticket status
codmir mcp done TKT-42
codmir mcp start TKT-42

# List available tools
codmir mcp tools

# Call any tool directly
codmir mcp call create_ticket '{"projectId":"proj_123","title":"Fix crash"}'

# Start the MCP stdio server
codmir mcp serve

SDK usage (programmatic)

import { MCPClient } from '@codmir/sdk/mcp';

const mcp = new MCPClient({
  apiUrl: 'https://codmir.com',
  token: process.env.CODMIR_API_TOKEN!,
  userId: process.env.CODMIR_USER_ID!,
});

// List to-do items
const todos = await mcp.listTodo({ projectId: 'proj_123' });

// Mark as done
await mcp.updateTodoStatus({
  projectId: 'proj_123',
  ticketId: 'TKT-42',
  status: 'done',
});

// Execute an AI task
await mcp.executeTask({
  projectId: 'proj_123',
  instructions: 'Add rate limiting to /api/auth',
});

// Call any tool
await mcp.callTool('get_project_context', { projectId: 'proj_123' });

Troubleshooting

"Not authenticated" error

codmir login
# Or check: cat ~/.codmir/credentials.json

MCP server not connecting

Restart your editor after updating the config. Test manually:

npx @codmir/mcp
# or
codmir mcp serve

Debug mode

DEBUG=codmir:mcp npx @codmir/mcp

Links

• Documentation
• SDK Docs
• CLI Reference
• GitHub

License

MIT