convez.ai
MCP ServerIntegração & APIsAvançado
verevoir

Verevoir MCP

verevoir/mcp

Unifica GitHub, Notion, Trello e Obsidian para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe o Verevoir como ferramentas utilizáveis por Claude Code, integrando múltiplas fontes (GitHub, sistemas de arquivos, Notion, Trello, Obsidian) através de uma única interface. Oferece leitura em cache, busca de símbolos com tree-sitter e operações de kanban/issues/objetivos.

Instalação

$npx convez-ai verevoir/mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
2
Acompanhando
0
Saúde
50%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar repositórios GitHub com workflows e quadros Kanban
  • Buscar símbolos e contexto de código em múltiplas fontes simultaneamente
  • Gerenciar issues, objetivos e kanban boards via Claude Code com escrita em cache

Veredito

Solução robusta para times que usam múltiplas plataformas (GitHub, Notion, Trello, Obsidian) e precisam de integração unificada com agentes IA. Exige configuração de credenciais e conhecimento técnico, mas oferece abstração poderosa sobre heterogêneas fontes de contexto e fluxo de trabalho.

README

A tradução para o português deste README ainda está na fila.

@verevoir/mcp

MCP server exposing the Verevoir foundation as Claude-Code-usable tools. Cached file reads, tree-sitter symbol search, and kanban / issue / objective operations behind one stdio MCP process.

Purpose

Lets an LLM agent (or anyone driving Claude Code) work against multiple sources — GitHub repos, local filesystems, Notion workspaces, Trello boards, and Obsidian Kanban boards — through one stable tool surface. Reads are cached via @verevoir/context; writes go through the underlying adapter and populate the cache so subsequent reads see the new content without a refetch.

Sibling to @verevoir/sources, @verevoir/context, and @verevoir/workflows. This package wires them together as an MCP server.

Prerequisites

  • Node >=20.
  • One or more of:
    • GitHub PAT — fine-grained, with Contents: Read + Write on whichever repos you want the tools to touch. Add Pull requests: Read + Write and Workflows: Read + Write if you'll expand the tool surface later.
    • Trello Power-Up — created at https://trello.com/power-ups/admin. From the Power-Up's API Key tab, generate the API key + the user token (the "Token" hyperlink on the same page). Note the allowed-origin URL — the MCP server must send it as the Referer or Trello returns 401.
    • Notion integration — create one at https://www.notion.so/profile/integrations, then share the relevant pages / databases with the integration from Notion's "Connections" UI. The integration token (ntn_…) is what you set as NOTION_API_KEY.
    • Obsidian Kanban — no credentials required. Pass the absolute path (or file:// URL) to a Kanban board .md as boardUrl. Optional tuning via env vars read at call time: OBSIDIAN_VAULT_PATH, OBSIDIAN_ID_FIELD (default id), OBSIDIAN_CARD_FOLDER, OBSIDIAN_DATE_FIELD (default due), OBSIDIAN_TAGS_FIELD (default tags).

Install

Option A — via npm (recommended for stable use)

npm install -g @verevoir/mcp

Or invoke via npx (no global install).

Option B — local path (recommended while iterating on the server)

Clone, build, and point your MCP config at the local dist/bin.js. Skips the publish cycle on every server change.

git clone git@github.com:verevoir/mcp.git
cd mcp
npm install
npm run build

Configuration in Claude Code

Add to ~/.claude/mcp.json:

Option A — npm

{
  "mcpServers": {
    "verevoir": {
      "command": "npx",
      "args": ["-y", "@verevoir/mcp"],
      "alwaysLoad": true,
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "TRELLO_API_KEY": "...",
        "TRELLO_API_TOKEN": "...",
        "TRELLO_REFERER": "https://your-power-up-origin",
        "NOTION_API_KEY": "ntn_..."
      }
    }
  }
}

Option B — local path

{
  "mcpServers": {
    "verevoir": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/bin.js"],
      "alwaysLoad": true,
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "TRELLO_API_KEY": "...",
        "TRELLO_API_TOKEN": "...",
        "TRELLO_REFERER": "https://your-power-up-origin",
        "NOTION_API_KEY": "ntn_..."
      }
    }
  }
}

Restart Claude Code (the MCP server loads at session start; claude --resume works too — it spawns a new process which re-reads mcp.json).

Pointing the server at a project (aigency.json)

The server injects an operating doctrine into the model's context on connect. When it can find a project pointer manifest (aigency.json, per ADR 023), it appends a project-specific section naming this project's work tracker, project record, and ADR database as concrete Notion URLs.

Discovery (per ADR 023): the server reads aigency.json from its working directory, overridable with a --manifest <path> arg. Add it after the script path:

"args": ["/absolute/path/to/mcp/dist/bin.js", "--manifest", "/absolute/path/to/project/aigency.json"]

Without a manifest the server runs in no-project mode — it still starts and serves the universal doctrine; only the project-specific section is omitted.

Why "alwaysLoad": true

Without this flag, Claude Code auto-defers MCP tool schemas when total tool definitions exceed ~10% of the context window — only tool names are sent up front; the model must call ToolSearch to load each schema before using it. That extra step makes the verevoir tools lose against always-on shell reflex (grep, cat, find) at the moment of choosing a tool — defeating the cache + freshness benefits of the MCP layer. alwaysLoad: true (Claude Code v2.1.121+) forces every tool from this server into the session at startup, so read_file / grep / find_symbol / list_cards are reflex-reachable. Older Claude Code versions ignore the flag (no breakage). The cost is ~2–5KB of context — worth it.

Env vars are read per-tool: GitHub tools only need GITHUB_TOKEN; Trello tools only need the three TRELLO_* vars; Notion tools (both source and workflow) only need NOTION_API_KEY. The server starts regardless of which are set — missing-env errors surface at tool-call time with clear messages naming the variable.

Sanity check

Once configured + restarted, ask Claude to call list_columns against your Trello board. You should get an array of columns back. If you see "TRELLO_API_KEY not set" or "Trello returned 401: invalid key", the auth env or the Power-Up referer mismatch is the cause.

Prompts

The server also registers the guardrails reasoning skills (corpus/skills/*.md) as MCP prompts. Invoking a prompt returns the skill's instructions plus your supplied arguments as a message for your model to execute — so a skill runs on the host's own tokens. Deterministic (handler-backed) skills are not registered as prompts; the host usually already has those capabilities. The corpus source defaults to the canonical guardrails repo and is overridable with AIGENCY_GUARDRAILS_URL; loading is best-effort, so a missing GITHUB_TOKEN simply means no skill prompts are registered. Requires an MCP client that supports prompts.

Tools

Source tools (file-shape sources)

All take a sourceUrl and route to the appropriate cached adapter:

  • https://github.com/owner/repo → cached GitHub adapter.
  • https://www.notion.so/<workspace>/<page-id> (or any notion.so URL form) → cached Notion adapter. Pages become "files"; child pages become "subdirectories"; reads/writes traverse path through the page tree.
  • Absolute filesystem path (or file://...) → cached FS adapter.
ToolArgsReturns
read_file{ sourceUrl, path, ref? }{ content, sha }
list_files{ sourceUrl, prefix?, ref? }DirEntry[]
get_repo_tree{ sourceUrl, ref? }RepoTree
grep{ sourceUrl, pattern, ref?, ignoreCase?, maxResults? }GrepHit[]
find_symbol{ sourceUrl, name, ref?, kind? }SymbolHit[]
write_file{ sourceUrl, path, content, branch, commitMessage }{ ok: true }

grep and find_symbol operate on cached content only — call read_file first on any files you want searchable. The cache is per-process, lazy-population.

Workflow tools (kanban / issue / objective sources)

All take a boardUrl:

  • https://trello.com/b/<id> → Trello adapter.
  • https://www.notion.so/<workspace>/<db-id>?v=... (or any notion.so URL form pointing at a database) → Notion adapter. Rows become Cards; auto-detects which property is the status / column from the database schema.
  • Absolute filesystem path or file:// URL → Obsidian Kanban adapter. Local board .md; ## headings are columns; - [ ] [[Note]] wikilinks are cards; the linked note is the card source of truth; no credentials required.
ToolArgsReturns
list_columns{ boardUrl }Column[]
list_cards{ boardUrl, columnId?, assigneeId?, labelId?, parentId? }Card[]
get_card{ boardUrl, cardId }Card
create_card{ boardUrl, columnId, title, body?, labelIds?, dueDate? }Card
update_card{ boardUrl, cardId, title?, body?, columnId?, labelIds?, dueDate? }{ ok: true }
move_card{ boardUrl, cardId, toColumnId }{ ok: true }
list_comments{ boardUrl, cardId }Comment[]
add_comment{ boardUrl, cardId, body }{ ok: true }

What this is NOT

  • Not a sync engine. Each tool is one operation; cross-backend mirroring lives elsewhere.
  • Not a code editor. Reads + writes pass through adapters; no in-memory text editing primitives.
  • Not opinionated about backends. URL routing picks the implementation; the protocol stays uniform.

See also

License

Apache-2.0.

Ver o original no GitHub

Bom para

Relacionados