mapj-mcp

name: mapj-mcp description: > MCP (Model Context Protocol) server that exposes mapj's search, fetch, filter discovery, TDN space listing, and live Protheus ERP query capabilities to any MCP-compatible client (Claude Desktop, Cursor, Claude Code, etc.) over stdio JSON-RPC 2.0 (protocol 2025-06-18). Use when you want to plug mapj into an AI agent runtime as a tool provider instead of invoking mapj from the shell. Do NOT use for one-off CLI queries — use 'mapj search' / 'mapj fetch' commands directly for those. Triggers: "set up MCP", "configure Claude Desktop", "agent tool integration", "expose mapj as MCP server", "wire mapj into Cursor", "query Protheus ERP". compatibility: No authentication for default sources. BRAVE_API_KEY env var enables Brave Search adapter. EXA_API_KEY env var enables Exa semantic search. yt-dlp binary on PATH required for YouTube transcripts. Protheus profiles must be pre-configured with 'mapj protheus connection add'. metadata: version: 2.0.0 language: en author: Mario Pereira tags: - mcp - jsonrpc - stdio - claude-desktop - cursor - tools - protheus - erp capabilities: - search-tool - fetch-tool - list-filters-tool - list-spaces-tool - protheus-query-tool - json-rpc-2.0 - tools-list - tools-call

allowed-tools: Bash

mapj-mcp — Agent Skill v2.0 (MCP 2025-06-18)

Run mapj as an MCP server (mapj mcp serve or the standalone mapj-mcp binary). Reads JSON-RPC 2.0 requests on stdin, writes responses on stdout, logs to stderr.

Tools exposed (8 tools)

All tools carry outputSchema and annotations (readOnlyHint: true, idempotentHint: true, destructiveHint: false).

See full schemas in tools/list response or in mapj/internal/schema/schemas.go.

protheus_query safety layers

1. ValidateReadOnly: rejects non-SELECT/WITH/EXEC and forbidden keywords
2. Auto-inject TOP N: bare SELECT without TOP clause gets TOP 1000 auto-added
3. Hard 30s timeout via context.WithTimeout
4. Client-side row cap (default 1000, max 10000)
5. Audit log: every call logged to $CACHE/mapj/audit-protheus.jsonl

Input: { query, profile_name?, max_rows? } — never accepts raw connection strings.

How to configure a client

Claude Desktop / Claude Code

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "totvs-docs": {
      "command": "C:/path/to/mapj-mcp.exe",
      "env": {
        "BRAVE_API_KEY": "<optional>",
        "EXA_API_KEY":   "<optional>",
        "MAPJ_LOG_LEVEL": "info"
      }
    }
  }
}

Cursor

.cursor/mcp.json in the project:

{
  "mcpServers": {
    "totvs-docs": {
      "command": "/path/to/mapj-mcp",
      "args": []
    }
  }
}

Alternative: invoke via Cobra

mapj mcp serve is equivalent to mapj-mcp (same code, just routed through Cobra). Useful if you don't want to ship the second binary.

Protocol summary

JSON-RPC 2.0 errors: -32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params.

Tool-level errors come back as result.isError=true with a text content block — the LLM can recover gracefully.

Examples (manual JSON-RPC)

# List exposed tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | mapj-mcp

# Search (default 10 results, all 7 native adapters, default lang="any" = no locale filter)
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"search_totvs_docs",
  "arguments":{"query":"NF-e inutilizar","max_results":10}
}}' | mapj-mcp

# Search with explicit locale filter (only returns docs tagged pt-br; excludes es/en-us).
# Use sparingly — the TOTVS corpus is mostly pt-br but has ES/EN translations you
# probably want visible. Default "any" is recommended for multilingual agents.
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"search_totvs_docs",
  "arguments":{"query":"NF-e inutilizar","lang":"pt-br"}
}}' | mapj-mcp

# Discover valid --lines filter values before searching
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"list_totvs_filters","arguments":{}
}}' | mapj-mcp

# List TDN spaces
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{
  "name":"list_tdn_spaces","arguments":{}
}}' | mapj-mcp

# Query Protheus ERP (SELECT-only; profile must exist in local auth store)
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{
  "name":"protheus_query",
  "arguments":{"query":"SELECT TOP 10 A1_COD, A1_NOME FROM SA1010","profile_name":"DEV"}
}}' | mapj-mcp

# Fetch a doc
echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{
  "name":"fetch_totvs_doc",
  "arguments":{"target":"tdn:66617420"}
}}' | mapj-mcp

Operational notes

• The server is concurrency-safe; multiple requests can pipeline.
• All progress/error logs go to stderr so the JSON-RPC stream on stdout is clean.
• Cache: pkg/cst and pkg/poui use in-memory caches; no disk cache yet.
• Per-source timeout default: 12s. protheus_query has a hard 30s timeout.
• protheus_query writes every call to $CACHE/mapj/audit-protheus.jsonl.

Failure modes the agent should expect