ProductPlan MCP Server

1. Encontre seu arquivo de configuração:

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

2. Abra-o em qualquer editor de texto e adicione isto (substitua your-token pelo seu token real da API):

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. Reinicie o Claude Desktop

Adicione ao seu arquivo de configuração:

• 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. Abra o Cursor
2. Vá em Configurações → Servidores MCP
3. Adicione esta configuração:

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

Usuários de Windows: Use barras invertidas duplas (\\) no caminho. Isso é necessário porque a barra invertida é um caractere de escape em JSON.

1. Instale a extensão Cline
2. Abra as configurações do VS Code (JSON) e adicione:

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. Instale a extensão Continue
2. Adicione ao seu arquivo de configuração:
   • 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. Defina a variável de ambiente na sua instância do n8n:

   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
   

2. Adicione um nó Cliente MCP ao seu fluxo de trabalho
3. Configure:
   • Comando:
     • Mac/Linux: /usr/local/bin/productplan
     • Windows: C:\Tools\productplan.exe
   • Variáveis de Ambiente: PRODUCTPLAN_API_TOKEN=your-token
4. Conecte a um nó Agente de IA

Exemplo de fluxo de trabalho: 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

Requer Go 1.26 ou mais recente.

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

Compilar para todas as 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

Execute todos os testes:

go test ./...

Execute com cobertura:

go test ./... -cover

Execute benchmarks:

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

Execute o conjunto de avaliação:

./scripts/run-evals.sh

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

Todo arquivo de produção atinge 10.0 em CodeScene Code Health (dois arquivos somente de tipos não podem ser pontuados).

50 ferramentas disponíveis: 35 ferramentas READ e 15 ferramentas WRITE (12 manage_* baseadas em ações mais 3 ferramentas de barra bulk_*):

Ferramentas de leitura:

• 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
• Descoberta: list_ideas, get_idea, list_all_customers, list_all_tags, list_opportunities, get_opportunity, list_idea_forms, get_idea_form
• Lançamentos: list_launches, get_launch, get_launch_sections, get_launch_section, get_launch_tasks, get_launch_task
• Administração: check_status, health_check, list_users, list_teams

Ferramentas de escrita:

• Roadmaps: manage_bar, manage_lane, manage_milestone
• Relacionamentos de barras: manage_bar_connection, manage_bar_link
• Barras em lote: bulk_update_bars, bulk_create_bars, bulk_delete_bars (até 100 barras por chamada, validadas antecipadamente, dry_run suportado)
• OKRs: manage_objective, manage_key_result
• Descoberta: manage_idea, manage_opportunity
• Lançamentos: manage_launch, manage_launch_section, manage_launch_task

Exemplo:

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

O servidor usa uma arquitetura limpa em camadas:

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

Interfaces principais:

// 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 (logging):

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