ProductPlan MCP Server

1. Encuentra tu archivo de configuración:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Ábrelo en cualquier editor de texto y agrega esto (reemplaza your-token con tu token de API real):

Mac/Linux:

{
  "mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

3. Reinicia Claude Desktop

Agrega a tu archivo de configuración:

• Mac/Linux: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json

Mac/Linux:

{
  "mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

1. Abre Cursor
2. Ve a Configuración → Servidores MCP
3. Agrega esta configuración:

Mac/Linux:

{
  "productplan": {
    "command": "/usr/local/bin/productplan",
    "env": {
      "PRODUCTPLAN_API_TOKEN": "your-token"
    }
  }
}

Windows:

{
  "productplan": {
    "command": "C:\\Tools\\productplan.exe",
    "env": {
      "PRODUCTPLAN_API_TOKEN": "your-token"
    }
  }
}

Usuarios de Windows: Usa dobles barras invertidas (\\) en la ruta. Esto es necesario porque la barra invertida es un carácter de escape en JSON.

1. Instala la extensión Cline
2. Abre la configuración de VS Code (JSON) y agrega:

Mac/Linux:

{
  "cline.mcpServers": {
    "productplan": {
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

Windows:

{
  "cline.mcpServers": {
    "productplan": {
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  }
}

1. Instala la extensión Continue
2. Agrega a tu archivo de configuración:
   • Mac/Linux: ~/.continue/config.json
   • Windows: %USERPROFILE%\.continue\config.json

Mac/Linux:

{
  "mcpServers": [
    {
      "name": "productplan",
      "command": "/usr/local/bin/productplan",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  ]
}

Windows:

{
  "mcpServers": [
    {
      "name": "productplan",
      "command": "C:\\Tools\\productplan.exe",
      "env": {
        "PRODUCTPLAN_API_TOKEN": "your-token"
      }
    }
  ]
}

1. Configura la variable de entorno en tu instancia de n8n:

   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
   

2. Agrega un nodo de Cliente MCP a tu flujo de trabajo
3. Configura:
   • Comando:
     • Mac/Linux: /usr/local/bin/productplan
     • Windows: C:\Tools\productplan.exe
   • Variables de entorno: PRODUCTPLAN_API_TOKEN=your-token
4. Conéctalo a un nodo de Agente de IA

Ejemplo de flujo de trabajo: Slack Trigger → AI Agent (with MCP Client) → Slack Response

productplan-mcp-server/
├── cmd/productplan/main.go      # Entry point: token check, then MCP server or CLI
├── internal/
│   ├── api/                     # ProductPlan API client
│   │   ├── client.go            # HTTP client: auth, rate limiting, error wrapping
│   │   ├── transport.go         # Tuned HTTP transport
│   │   ├── cache.go             # In-process TTL read cache (singleflight, write invalidation)
│   │   ├── list.go              # Paged collection GETs and Ransack query encoding
│   │   ├── ids.go               # Typed resource IDs (BarID, RoadmapID, ...), each validated into a path segment
│   │   ├── path.go              # Routes and request paths built only from typed IDs
│   │   ├── safeseg.go           # Path-segment validation for user-supplied IDs
│   │   ├── endpoints*.go        # Endpoint methods (roadmaps, bars, ideas, launches, OKRs)
│   │   ├── bars_read.go         # Roadmap bars with lane enrichment and client-side filters
│   │   ├── bar_schema.go        # Roadmap legends/lanes/custom fields for bar writes
│   │   └── formatters.go        # Response projection for AI
│   ├── mcp/                     # MCP wiring over the official go-sdk
│   │   ├── sdk_server.go        # Serves the registry via go-sdk (stdio)
│   │   ├── sdk.go               # Converts local Tool -> SDK tool
│   │   ├── handler.go           # Registry: dispatch and panic recovery
│   │   ├── argkeys.go           # Rejects undeclared argument keys (did-you-mean)
│   │   ├── editdistance.go      # Levenshtein distance for suggestions
│   │   └── types.go             # Tool-authoring types
│   ├── tools/                   # Tool definitions and handlers
│   │   ├── registry.go          # Tool registration (name -> handler)
│   │   ├── definitions*.go      # Tool schemas and descriptions
│   │   ├── helpers.go           # typedHandler, manage-action dispatch
│   │   ├── filters.go           # List-tool filters -> Ransack predicates
│   │   ├── formatter.go         # List/item/action response summaries
│   │   ├── item_type.go         # Item nouns for summaries
│   │   ├── bar_planner.go       # Validates bar writes against the roadmap
│   │   ├── bar_names.go         # Legend/lane/custom field name resolution
│   │   ├── bulk_bars.go         # bulk_update/create/delete_bars
│   │   ├── roadmaps.go, bars.go, ideas.go, objectives.go, launches.go, utility.go  # handlers
│   │   └── types*.go            # Typed argument structs for handlers
│   ├── cli/                     # CLI commands (status, roadmaps, etc.)
│   │   └── cli.go
│   └── logging/                 # slog JSON handler setup (ts/level/msg)
│       └── logger.go
├── pkg/productplan/             # Reusable utilities
│   ├── retry.go                 # Exponential backoff with jitter
│   ├── ratelimit.go             # Adaptive rate limiting
│   ├── batch.go                 # Batched operations
│   ├── health.go                # Health reporting
│   ├── requestid.go             # Request tracing
│   ├── validation.go            # ID validation (Field.RequireID)
│   └── errors.go                # APIError and error suggestions
└── evals/                       # LLM evaluation test suite
    ├── runner.go, types.go
    ├── tool_selection.json
    ├── confusion_pairs.json
    └── argument_correctness.json

Requiere Go 1.26 o superior.

git clone https://github.com/olgasafonova/productplan-mcp-server.git
cd productplan-mcp-server
go build -o productplan ./cmd/productplan

Compilar para todas las plataformas:

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o dist/productplan-darwin-arm64 ./cmd/productplan

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o dist/productplan-darwin-amd64 ./cmd/productplan

# Linux
GOOS=linux GOARCH=amd64 go build -o dist/productplan-linux-amd64 ./cmd/productplan

# Windows
GOOS=windows GOARCH=amd64 go build -o dist/productplan-windows-amd64.exe ./cmd/productplan

Ejecutar todas las pruebas:

go test ./...

Ejecutar con cobertura:

go test ./... -cover

Ejecutar benchmarks:

go test ./internal/... -bench=. -benchmem

Ejecutar el conjunto de evaluación:

./scripts/run-evals.sh

Cobertura (medida el 24-09-2026, go test ./... -cover):

Cada archivo de producción obtiene 10.0 en CodeScene Code Health (dos archivos solo de tipos no pueden ser evaluados).

50 herramientas disponibles: 35 herramientas READ y 15 herramientas WRITE (12 basadas en acciones manage_* más 3 herramientas de barra bulk_*):

Herramientas de lectura:

• Roadmaps: list_roadmaps, get_roadmap, get_roadmap_bars, get_roadmap_lanes, get_roadmap_milestones, get_roadmap_legends, get_roadmap_comments, get_roadmap_complete
• Barras: get_bar, get_bar_children, get_bar_comments, get_bar_connections, get_bar_links
• OKRs: list_objectives, get_objective, list_key_results, get_key_result
• Descubrimiento: list_ideas, get_idea, list_all_customers, list_all_tags, list_opportunities, get_opportunity, list_idea_forms, get_idea_form
• Lanzamientos: list_launches, get_launch, get_launch_sections, get_launch_section, get_launch_tasks, get_launch_task
• Administración: check_status, health_check, list_users, list_teams

Herramientas de escritura:

• Roadmaps: manage_bar, manage_lane, manage_milestone
• Relaciones de barras: manage_bar_connection, manage_bar_link
• Barras masivas: bulk_update_bars, bulk_create_bars, bulk_delete_bars (hasta 100 barras por llamada, validadas de antemano, dry_run compatible)
• OKRs: manage_objective, manage_key_result
• Descubrimiento: manage_idea, manage_opportunity
• Lanzamientos: manage_launch, manage_launch_section, manage_launch_task

Ejemplo:

{"tool": "list_roadmaps", "arguments": {}}
{"tool": "manage_bar", "arguments": {"action": "create", "roadmap_id": "123", "lane": "Backend", "name": "New feature", "legend": "Committed"}}
{"tool": "bulk_update_bars", "arguments": {"set": {"legend": "Committed"}, "items": [{"bar_id": "901"}, {"bar_id": "902"}], "dry_run": true}}
{"tool": "manage_idea", "arguments": {"action": "create", "name": "Mobile app improvements"}}

El servidor utiliza una arquitectura limpia por capas:

┌──────────────────────────────────────────────────────────────┐
│                        cmd/productplan                        │
│                     (entry point, DI)                         │
└──────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  internal/cli │    │  internal/mcp │    │internal/tools │
│  (CLI cmds)   │    │  (MCP / SDK)  │    │  (handlers)   │
└───────────────┘    └───────────────┘    └───────────────┘
                              │                     │
                              └──────────┬──────────┘
                                         ▼
                              ┌───────────────────┐
                              │   internal/api    │
                              │  (HTTP client)    │
                              └───────────────────┘
                                         │
                                         ▼
                              ┌───────────────────┐
                              │  ProductPlan API  │
                              └───────────────────┘

Interfaces clave:

// Tool handler interface (internal/mcp)
type Handler interface {
    Handle(ctx context.Context, args map[string]any) (json.RawMessage, error)
}

// Logging (internal/logging): a *slog.Logger with a JSON handler on stderr
logger := logging.New(slog.LevelInfo)

Formato de registro:

{"ts":"2026-09-24T10:30:00.123456789Z","level":"debug","msg":"API response","endpoint":"/roadmaps/5","status_code":200,"dur_ms":245}