Back to Browse

Rational MCP Server

Developer ToolsModerate6.3MCP RegistryLocal
Free

Server data from the Official MCP Registry

Vendor-agnostic governance & traceability layer for AI coding agents (MCP + CLI).

About

Vendor-agnostic governance & traceability layer for AI coding agents (MCP + CLI).

Security Report

6.3
Moderate6.3Moderate Risk

This is a local, stdio-based governance layer whose visible code makes no network calls and has no shell execution, and its file access stays within the project directory. The main concerns are untrusted scope and file-path parameters passed to memory and tag tools, which could allow path traversal if the unseen store modules do not validate them, plus unpinned npx auto-install in the generated agent configs. Permissions match the stated purpose. Supply chain analysis found 2 known vulnerabilities in dependencies (0 critical, 1 high severity). Package verification found 1 issue.

8 files analyzed ยท 9 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "rational-agnostic": {
      "command": "npx",
      "args": [
        "-y",
        "rational-agnostic@0.1.7"
      ]
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

rational-agnostic

npm version install size license node

A vendor-agnostic, file-based governance & traceability layer for AI coding agents.

rational-agnostic sits above any agent framework (Claude Code, Codex, Cursor, Copilot, Jules, โ€ฆ). It is the shared, durable record that agents of any vendor read from and write to:

  • ๐Ÿง  Decisions โ€” every non-trivial choice is recorded as an ADR-style file explaining why (in English).
  • ๐Ÿ”— Traceability โ€” every generated function carries a // @why: D-xxxx tag; you can take a function, hash it, and find the decision behind it.
  • ๐Ÿค Shared memory โ€” a cross-vendor meeting point so agents don't lose context between sessions or between each other.
  • โœ… Task state โ€” one file per task + a status board, so everyone knows what's doing, blocked or done.
  • ๐Ÿ“š Learnings โ€” the system distills recurring patterns from past decisions and code, and keeps improving.
  • ๐ŸŽฏ Token-aware context โ€” get_context returns a minimal relevant bundle within a token budget, instead of dumping history.

Everything is persisted in English, even when the user works in another language, so the knowledge base stays portable, searchable and diffable.

Design principle: AGENTS.md describes how the system is structured and used โ€” never what your project is about. Project rationale lives in the decision records.

Install

npm install -g rational-agnostic   # or: npx rational-agnostic <command>

Quickstart

Every project starts with init, which scaffolds AGENTS.md, the .rational-agnostic/ store, and wires every major AI agent (see Zero-config agent wiring):

cd your-repo
rational-agnostic init            # creates AGENTS.md + .rational-agnostic/

Already have a codebase? Run adopt (brownfield)

If the repo already had code before rational-agnostic, don't start from a blank slate โ€” have it inventory what exists and lay out an onboarding plan. This is the recommended path for any non-empty project:

rational-agnostic init            # 1. scaffold (adopt needs this first)
rational-agnostic adopt           # 2. read-only inventory + plan:
                                  #    languages, manifests, entry points,
                                  #    largest/most-central files, tag coverage
rational-agnostic adopt --write   # 3. persist an "as-built" baseline decision,
                                  #    open an adoption task, post a brief to
                                  #    shared memory โ€” then point your agent here

Nothing breaks on day one: existing untagged code is allowed (verify only flags @why tags that point to a missing decision, never legacy code). From there you work the plan incrementally โ€” largest/most central modules first โ€” recording a decision and tagging the code for each design choice you can infer. Never invent rationale: if you can't tell why something exists, ask (append a question to shared memory) instead of fabricating a decision.

MCP-capable agents have the same two steps as the adopt_report and start_adoption tools.

Record a decision and tag the code

Record a decision and tag the code it justifies:

rational-agnostic decision add \
  --title "Use JWT for auth" \
  --summary "Chose JWT over sessions for stateless scaling" \
  --context "API must scale horizontally without sticky sessions" \
  --decision "Short-lived JWT access tokens + refresh tokens" \
  --why "Stateless tokens avoid shared session storage" \
  --author agent:anthropic:claude-code --tags auth,security
# -> Created D-ea3ec7 โ€” tag code with:  // @why: D-ea3ec7
// @why: D-ea3ec7
function issueToken(user) { /* ... */ }

Find why a function exists โ€” by location or by hash:

rational-agnostic why src/auth.js issueToken
printf '%s' "$(cat the-body)" | rational-agnostic hash   # -> sha256
rational-agnostic why --hash <sha256>

Gate your commits with traceability:

rational-agnostic init --hook     # installs a pre-commit `verify` gate
rational-agnostic verify          # exit 1 on orphan tags / bad task status

Zero-config agent wiring

init doesn't just scaffold the data store โ€” it wires every major AI agent for you, so whoever runs npx rational-agnostic init gets a ready-to-use setup with no manual MCP configuration. It generates (and safely merges into, never clobbers) the file each client actually reads:

AgentMCP config writtenInstructions file
Claude Code.mcp.json (auto-discovered)CLAUDE.md โ†’ AGENTS.md
Cursor.cursor/mcp.jsonAGENTS.md
Codex.codex/config.tomlAGENTS.md
Gemini CLI.gemini/settings.jsonGEMINI.md โ†’ AGENTS.md
Copilot.vscode/mcp.json.github/copilot-instructions.md โ†’ AGENTS.md

Open any of those agents in the repo and the MCP server + protocol are already in place (restart the client once to load MCP; approve/trust it if prompted). Opt out with rational-agnostic init --no-mcp.

The CLI needs none of this โ€” every operation is also a command, so any agent can use rational-agnostic with zero setup by running npx rational-agnostic โ€ฆ straight from AGENTS.md. MCP is just a more token-efficient interface on top.

Connect an AI agent (MCP) manually

If a client wasn't auto-wired, add this stdio server to its config:

{
  "mcpServers": {
    "rational-agnostic": { "command": "npx", "args": ["-y", "rational-agnostic", "mcp"] }
  }
}

The agent then sees 22 tools โ€” get_context, search, record_decision, tag_code, create_task, set_task_status, read_memory, append_memory, record_learning, distill, verify, and more. Agents are told how to use them by the generated AGENTS.md.

What gets stored

AGENTS.md                      generic manifest: how to use the package + where things live
.rational-agnostic/
  config.json                  locale, canonical "en", embeddings provider, verify rules
  decisions/   D-*.md          one decision per file (Context / Decision / Why / Consequences)
  tasks/       T-*.md           one task per file
               board.json       status index
  memory/      shared.md        cross-agent shared memory
               agents/*.md      per-agent scratch
  knowledge/   learnings.md     accumulated learnings
               conventions.md   emergent conventions
  index/       registry.json    code anchor -> decision map (+ SHA for drift)
               embeddings/       rebuildable semantic index (gitignored)

Semantic retrieval & tokens

Search and get_context use embeddings. Out of the box they run on a deterministic lexical embedder with zero extra dependencies โ€” nothing to download, no network, no native binaries. For higher-quality semantic search you can opt into a local, offline transformer model (Xenova/all-MiniLM-L6-v2, no API key) by installing it yourself:

npm install @huggingface/transformers    # optional; enables the local model

It is not a dependency on purpose: it pulls sharp/onnxruntime (~135 MB, and the source of the libvips/libheif/librsvg advisories if you add it). When absent, the lexical fallback keeps search working everywhere; when present, the code detects and uses it automatically. The vector index is a rebuildable cache โ€” the markdown files are always the source of truth:

rational-agnostic search "how are auth tokens issued"
rational-agnostic context --task T-0001 --budget 1500
rational-agnostic reindex

Library

import { init, decisions, getContext, verify } from "rational-agnostic";

Documentation

A detailed, self-contained explainer (what was built, why, and how it works) is in docs/how-it-works.html โ€” clone the repo and open it in a browser. Available in English (primary), Spanish, Chinese and Japanese via the in-page language switcher.

Security & footprint

The default install is deliberately lean and npm audit reports 0 vulnerabilities โ€” no native binaries, no install scripts, no network access at install time:

  • Heavy ML stack is opt-in. @huggingface/transformers (and its sharp / onnxruntime subtree, ~135 MB, which carried the libvips/libheif/librsvg advisories) is not declared as a dependency at all. The embedder loads it via a guarded, indirect dynamic import only if you install it yourself, so the default footprint stays ~27 MB and clean.
  • Small, trusted runtime deps. commander (CLI, zero-dep), gray-matter (YAML frontmatter), proper-lockfile (safe cross-process writes), zod โ‰ฅ 4.6.7 (schema validation, past the GHSA-mrhx-c7xc-m3w5 DoS) and the official @modelcontextprotocol/sdk.
  • Deliberately not reinvented. YAML frontmatter, cross-process locking and CLI parsing stay on their small, trusted libraries: a hand-rolled replacement would trade a negligible supply-chain reduction for real correctness risk (your decision records are hand-editable and must round-trip exactly).

Run npm audit any time to check the current state. Report a vulnerability via the repo's issues.

License

MIT ยฉ Paco Aguilera

Reviews

No reviews yet

Be the first to review this server!