lkpgestao-mcp

MCP server for LKPGestão — exposes the CEO cockpit API to Claude Cowork / Claude Desktop as tools and prompts.

• 49 tools covering resources, projects (full CRUD + team management, 10 tools), opportunities (full CRUD incl. 9 writes across opp / activity / contact, 12 tools), tasks (full CRUD + comments, 7 tools), clients, helpdesk (list, summary + ticket create), billing, alerts, CEO weekly report, and 3 composites (lkp_skill_match, lkp_weekly_brief, lkp_timesheet_anomalies).
• 5 slash prompts: /weekly-brief, /morning-standup, /opportunity-action, /consultant-investigation, /pipeline-health-check.
• Stdio JSON-RPC transport, zero network exposure.
• Structured stderr logs (pino) with token redaction; never leaks Authorization headers.

Requirements

• Node.js ≥ 20 (ships fetch natively).
• A Bearer token from LKPGestão at /settings/api-tokens with the scopes you need (read:* + write:opportunities + write:projects + write:tasks for the full catalog).

Install (Claude Desktop / Cowork)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "lkpgestao": {
      "command": "npx",
      "args": ["-y", "lkpgestao-mcp"],
      "env": {
        "LKP_API_BASE_URL": "https://lkpgestaodev.linkupconsultoria.com",
        "LKP_API_TOKEN": "<paste token from /settings/api-tokens>",
        "LKP_LOG_LEVEL": "info"
      }
    }
  }
}

Restart the client. First launch downloads the package via npx.

Configuration

| Var | Required | Default | Description | |---|---|---|---| | LKP_API_BASE_URL | ✓ | — | HTTPS base URL (trailing slashes stripped). HTTP is rejected. | | LKP_API_TOKEN | ✓* | — | Bearer token (without Bearer prefix). *Required unless LKP_API_TOKEN_KEYCHAIN_SERVICE is set. | | LKP_API_TOKEN_KEYCHAIN_SERVICE | | — | macOS only. Service name in the Keychain (-s flag of security find-generic-password). Used when LKP_API_TOKEN is absent. | | LKP_API_TOKEN_KEYCHAIN_ACCOUNT | | — | Optional account name (-a flag) to disambiguate Keychain entries. | | LKP_LOG_LEVEL | | info | trace/debug/info/warn/error/fatal/silent | | LKP_REQUEST_TIMEOUT_MS | | 10000 | Per-request HTTP timeout. | | LKP_RETRY_ATTEMPTS | | 2 | Retries on 5xx/network. 429 is retried once honoring Retry-After. | | LKP_CACHE_TTL_SECONDS | | 30 | Reserved for future read cache. |

Develop from source

git clone https://github.com/denisvandrade/lkpgestao-mcp.git
cd lkpgestao-mcp
npm install
npm run typecheck
npm test            # 110 unit tests (errors, config, keychain, http-client incl. DELETE/204 + Retry-After cap, logger redaction, timesheet detectors, projects-write, tasks incl. comments)
npm run build       # dist/index.js (ESM, shebang, ~59 KB)
node dist/index.js  # speaks MCP on stdio

Loading the token from macOS Keychain

To avoid storing the token in plaintext inside the MCP client config, use Keychain instead:

# Store once (prompts for the token)
security add-generic-password -s lkpgestao-mcp-token -a "$USER" -w

Then point the config at the Keychain entry — no secret touches disk:

{
  "mcpServers": {
    "lkpgestao": {
      "command": "lkpgestao-mcp",
      "env": {
        "LKP_API_BASE_URL": "https://lkpgestaodev.linkupconsultoria.com",
        "LKP_API_TOKEN_KEYCHAIN_SERVICE": "lkpgestao-mcp-token"
      }
    }
  }
}

The server shells out to /usr/bin/security at startup. If the lookup fails (item missing, user cancels the Keychain prompt), startup aborts with a clear error.

Security

• Token is loaded once at startup; never written to logs or tool results.
• pino redaction covers authorization, token, bearer fields in any log record — verified by integration tests that capture stderr and assert the token value never appears (including under headers.*, env.*, and child loggers).
• Keychain resolution uses execFileSync("security", [...]) with args as an array — service/account names are passed verbatim to the security binary; no shell interpretation, no injection surface.
• Retry-After values are capped at 60 s — a hostile or misconfigured server returning Retry-After: 99999 cannot hang the process for hours.
• Every request sends X-Request-ID (UUID v4) for cross-correlating stderr lines with API-side traces.
• Write tools (19 total: 9 opportunity writes — create/update/archive, activity add/update/delete, contact attach/update/detach; 6 project writes — create/update/archive, member add/update/remove; 4 task writes — create/update/archive/comment-add) require explicit user approval in the prompt contract — the server does not gate; the slash prompts and tool descriptions instruct the LLM to summarize and wait for confirmation before every destructive or state-changing call.

Documentation

| Document | Path | |---|---| | MCP Server Spec v1 | docs/specs/MCP_SPEC.md | | MCP Server Spec v2 (Phase F) | docs/specs/MCP_SERVER_SPEC_v2.md | | REST API Spec | docs/specs/API_SPEC_MCP.md | | Implementation Plan v2 | docs/plans/API_MCP_IMPLEMENTATION_PLAN_v2.md | | Implementation Plan v3 | docs/plans/API_MCP_IMPLEMENTATION_PLAN_v3.md |

License

UNLICENSED — internal LKP Consultoria use.