Mapj

Aggregated documentation search + retrieval CLI and MCP server for the TOTVS ecosystem. Built so AI agents can answer "how do I…" questions about Protheus, Datasul, RM, Fluig and the rest of the TOTVS stack from a single, dependable interface.

$ mapj search "NF-e inutilizar" --max-results 5
{"ok":true,"command":"mapj search","result":{
  "query":"NF-e inutilizar","total_found":372519,"returned":5,"execution_ms":612,
  "by_source":{"tdn":{"hits":3},"central":{"hits":2}},
  "items":[
    {"rank":1,"source":"tdn","title":"NF-e - Inutilizar numeração de NF-e",
     "html_url":"https://tdn.totvs.com/pages/viewpage.action?pageId=66617420",
     "score_norm":1.0,"fetch_url":"tdn:66617420"},
    ...
  ]
}}

---

Why mapj exists

TOTVS documentation is spread across a dozen heterogeneous systems: TDN (Confluence), Centraldeatendimento (Zendesk), Zendesk CST, the developer forum (Discourse), PO UI's static dataset, Espaço Legislação (WordPress), the YouTube channel, and Central de Downloads — each with its own auth model, search syntax, response shape and quirks.

Asking an AI agent to navigate that is a recipe for hallucinations. mapj collapses all of it into one envelope shape, one canonical id per document, one Markdown converter with YAML frontmatter, and an MCP server that drops directly into Claude Desktop, Cursor, Continue or anything that speaks JSON-RPC 2.0 over stdio.

What it does

• 🔍 mapj search "<query>" — fan-out across 9 adapters in parallel (CST + Forum + WP + PO UI + Zendesk direct + Brave + Exa), URL-deduped, weighted cross-source ranking.
• 📄 mapj fetch <id-or-url> — host-routed retrieval, returns Markdown with frontmatter for every supported source.
• 🤖 mapj mcp serve — drop-in MCP server exposing 5 tools: search_totvs_docs, fetch_totvs_doc, list_totvs_filters, list_tdn_spaces, protheus_query (live ERP queries, SELECT-only).
• 🛠️ mapj tdn, mapj confluence, mapj protheus — refined CQL search, page tree export, Protheus SQL queries with safety tripwires.
• 🎥 YouTube transcripts via yt-dlp — mapj fetch youtube:<id> returns timestamped Markdown.
• 🌐 Brave + Exa web fallback — keyword (Brave) and semantic (Exa) search restricted to TOTVS domains.

All commands speak a stable agent-first envelope:

{ "ok": true|false, "command": "mapj X", "result": {...}, "error": {...} }

with exit codes 0 success / 1 general / 2 usage / 3 auth / 4 retryable.

Quick demo

# Aggregated search — no auth required
$ mapj search "AdvPL ponto de entrada" --lines protheus --max-results 10

# Discover the canonical filter values before filtering
$ mapj search --list-filters

# Fetch a doc by canonical id (or raw URL)
$ mapj fetch tdn:66617420
$ mapj fetch central:360033272414
$ mapj fetch youtube:dQw4w9WgXcQ                # requires yt-dlp on PATH

# Add web results (Brave + Exa) when an env var is set
$ BRAVE_API_KEY=... EXA_API_KEY=... mapj search "configurar TOTVS Apps" --include-web

# Run as MCP server (Claude Desktop / Cursor / Continue plug in here)
$ mapj mcp serve

---

Installation

From release (recommended)

Download the latest binary for your platform from the GitHub release page:

• mapj-windows-amd64.exe
• mapj-linux-amd64
• mapj-darwin-arm64
• mapj-mcp-windows-amd64.exe (standalone MCP server)
• mapj-mcp-linux-amd64
• mapj-mcp-darwin-arm64

Verify the SHA-256 from SHA256SUMS.txt. No installer needed — single binary, drop on PATH.

From source

Needs Go 1.23+.

git clone https://github.com/Mario-pereyra/mapj
cd mapj
go build -o mapj.exe ./cmd/mapj
go build -o mapj-mcp.exe ./cmd/mapj-mcp

Optional dependencies (detected at runtime)

Dependency	Enables	How to install
yt-dlp on PATH	mapj fetch youtube:<id>	pip install -U yt-dlp or winget install yt-dlp
BRAVE_API_KEY env var	mapj search --include-web keyword results	https://api-dashboard.search.brave.com/ (2 000 free queries/month)
EXA_API_KEY env var	mapj search --include-web semantic results	https://dashboard.exa.ai/ (1 000 free queries/month)

When neither key is set, --include-web returns a warning and the search proceeds with just the TOTVS-native adapters. None of the keys are required for the public TOTVS sources.

---

Quick Start

Option A — CLI

mapj search "NF-e inutilizar" --max-results 10
mapj search --list-filters                          # see available product lines / produtos
mapj fetch tdn:66617420                             # retrieves Markdown
mapj fetch "https://centraldeatendimento.totvs.com/hc/pt-br/articles/360033272414-..."

Option B — MCP server in Claude Desktop / Cursor / Continue

Edit your client's MCP config. For Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):

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

The server exposes 5 tools (MCP 2025-06-18, all with outputSchema and annotations):

Tool	Purpose
search_totvs_docs	Multi-source aggregated search (7 native adapters + optional Brave/Exa)
fetch_totvs_doc	Retrieve a doc by canonical id or URL → Markdown
list_totvs_filters	Discover valid lines / produtos filter values from CST
list_tdn_spaces	List all TDN Confluence space keys and names
protheus_query	Live SELECT query on Protheus ERP SQL Server (read-only enforced, audit log)

See skills/mapj-mcp/SKILL.md for the full JSON Schemas.

Option C — Authenticate Confluence / Protheus (optional)

Only needed for private TDN content or Protheus database queries. Public TOTVS docs require no auth.

mapj auth login confluence --url https://tdninterno.totvs.com --token YOUR_PAT
mapj protheus connection add MYDB \
  --server 192.168.99.102 --database P1212410 --user U --password P --use

Zendesk authenticated mode (community posts + private articles) is not yet implemented. Blueprint persisted in docs/zendesk-auth-playwright-plan.md.

---

Architecture

mapj search "<query>"
  │
  ├── Layer 1: CST aggregator           (POST ti-services.totvs.com.br/cst/BUSCA)
  │     └─ One call → TDN + Centraldeatendimento + Zendesk CST
  │                   + YouTube + Central Downloads (real ES scores)
  │
  ├── Layer 2: Specialized adapters     (parallel fan-out, 12s timeout each)
  │     ├─ Discourse        forum.totvs.io/search.json
  │     ├─ WordPress        espacolegislacao.totvs.com/wp-json/wp/v2/search
  │     ├─ PO UI            static dataset /assets/json/api-list.json
  │     └─ Zendesk direct   article body, sections, labels
  │
  └── Layer 3: Web providers            (opt-in via API keys)
        ├─ Brave Search    api.search.brave.com  (keyword, soft site:)
        └─ Exa.ai          api.exa.ai            (semantic, strict includeDomains)
                            │
                            ▼
        cross-source URL dedup  +  weighted score normalization
                            │
                            ▼
                  ranked Items in one envelope

mapj fetch <target>
  └── Router by host or canonical prefix
      ├─ tdn:<id>          → Confluence export (MD + frontmatter + ancestors)
      ├─ central:<id>      → Zendesk article body → MD
      ├─ cst_zendesk:<id>  → totvscst Zendesk
      ├─ forum:<id>        → Discourse /t/<id>.json → MD
      ├─ youtube:<id>      → yt-dlp transcript + chapters → MD
      ├─ poui:<name>       → po-ui.io documentation page
      ├─ legislacao:<url>  → WordPress page HTML → MD
      └─ <https://...>     → host-detected fallback

19 Go packages, ~140 tests, go vet ./... clean. See AGENTS.md for a deep dive.

Output formats

Flag	Format	Best for
(default) auto	Best fit per result type	General use
-o llm	Compact JSON	Machine-readable deterministic parsing
-o toon	Tabular YAML	Token-efficient for LLM agents on tabular results (typically 15-30% smaller than JSON on search payloads; <5% on dense small-key catalogs). See docs/prd-token-efficiency.md §4.1 for measurements.
-o json	Pretty JSON	Human debugging

---

Project status

mapj is in active beta (v0.7.x). The agent-first envelope shape is stable across versions; new sources and tools are added under the same contract.

Area	Status
CST aggregator + TDN + Central + YouTube + Downloads	✅ Production
Discourse forum adapter	✅ Production
WordPress / PO UI adapters	✅ Production
Zendesk direct (public mode)	✅ Production
Brave + Exa web providers	✅ Production (opt-in via API keys)
YouTube transcripts via yt-dlp	✅ Production
MCP server — 5 tools (MCP 2025-06-18)	✅ Production
protheus_query — live ERP queries via MCP	✅ Production (SELECT-only + audit)
--schema CLI flag — emit JSON Schema per command	✅ Production
Zendesk authenticated (community posts, private articles)	📋 Planned — see docs/zendesk-auth-playwright-plan.md
Disk cache for multi-process MCP	📋 Planned

---

Documentation map

Document	What's in it
AGENTS.md	Architecture, conventions, anti-patterns. The SSOT for v0.5+. Read first if you're going to modify code.
CONTRIBUTING.md	Contribution workflow, commit conventions, documentation mandate, encryption internals.
CHANGELOG.md	Full version history.
docs/confluence-export-guide.md	Confluence concurrent export + resilience.
docs/protheus-guide.md	Protheus SQL safety tripwires + schema discovery.
docs/zendesk-auth-playwright-plan.md	Blueprint for the next phase (Zendesk authenticated mode).
docs/prd-token-efficiency.md	PRD for v0.6 token efficiency: 8 measured bugs + 13 proposed fixes ranked by ROI.
docs/tools-analysis-2026.md	Tool-by-tool audit (Protheus, Confluence, Search, Fetch, Schemas) vs SOTA mayo 2026.
docs/implementation-plan-v06.md	Execution plan for v0.5.1 / v0.6.0 / v0.7.0 — 30 sub-issues, calendar, dependencies. Tracking: #50
docs/README.md	Index of everything under docs/.
EVALUATION.md	Effectiveness/efficiency analysis vs Firecrawl, Tavily, Brave-alone, etc.
SECURITY.md	How to report vulnerabilities.
CODE_OF_CONDUCT.md	Contributor Covenant v2.1.

Agent skills

For agents that load skill files, pre-baked descriptions live under skills/:

• skills/mapj/ — orchestrator skill
• skills/mapj-search/ — aggregated search (v0.5.0)
• skills/mapj-mcp/ — MCP server setup + tool schemas (v0.5.0, 5 tools)
• skills/mapj-tdn-search/ — TDN CQL refinement
• skills/mapj-confluence-export/ — exports & attachments
• skills/mapj-protheus-query/ — SQL with prefix validation

---

Contributing

We accept:

• Bug reports via GitHub issues (use the templates).
• Feature requests that align with the project philosophy.
• New source adapters following the adapter checklist.
• Pull requests following the PR template.

Start with good-first-issue-labeled items. Be kind — see CODE_OF_CONDUCT.md.

For security issues, don't open a public issue; use the private security advisory or read SECURITY.md.

---

License

MIT. © 2026 Mario Pereyra and mapj contributors.

mapj retrieves documentation from third-party services. Users are responsible for complying with the terms of service of TDN, Zendesk, Discourse, WordPress, PO UI, YouTube, Brave Search and Exa.ai.

---

Acknowledgements

• TOTVS for the underlying documentation ecosystem and the public CST aggregator.
• Anthropic for the Model Context Protocol spec.
• Brave and Exa for offering independent search APIs with generous free tiers.
• yt-dlp maintainers for keeping a binary-only, dependency-free YouTube transcript path alive.
• Everyone who opens a useful issue — that's where new adapters come from.