@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 [email protected]: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.

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.

| Tool | Args | Returns | | --------------- | -------------------------------------------------------- | ------------------ | | 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.

| Tool | Args | Returns | | --------------- | --------------------------------------------------------------------- | -------------- | | 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

• @verevoir/sources — file-source contracts + GitHub + FS adapters.
• @verevoir/context — content + symbol cache; cached drop-in subpaths.
• @verevoir/workflows — workflow-source contracts + Trello adapter.
• @verevoir/llm — provider-agnostic LLM call surface.

License

Apache-2.0.