mithra-mcp

An MCP server that turns a one-person, multi-project workspace into state an agent can reason over — live git status, Kanban boards, tasks, standups, and production health, exposed as tools any MCP client can query in natural language.

I run six projects at once — a wedding-planning SaaS, a condo-admin platform, a game studio, a landing site, and the tooling that holds it together — as a single engineer. Context evaporates between sessions. Mithra is the local-first command-center I built on Claude Code primitives to keep all of it in view. This repo is one piece of it: the part that exposes my workspace over the Model Context Protocol, so any client — Claude Desktop, Claude Code — can ask about it instead of guessing from stale context.

"which repos are stale?"        → list_projects
"what should I attack first?"    → next_actions
"is prod up?"                    → deploy_health

The idea: bounded memory + retrieval, not a bigger prompt

Mithra is built on two convictions, each borrowed from work I admire.

Bounded working memory — after Hermes (Nous Research). An agent shouldn't drag an ever-growing transcript behind it. Mithra keeps a small, frozen working-memory snapshot — a few hundred words of current focus, live decisions, and open loops — injected at session start, with an alarm when it fills past ~80%. The bet: a tight, curated memory beats an unbounded one that quietly rots.

But a bounded memory can't hold everything — and shouldn't try. That's what this repo is for. Instead of stuffing workspace state into the prompt, Mithra leaves it where it lives and exposes it as queryable tools. The model carries a small memory and pulls live truth on demand. Bounded context, on-demand retrieval — the two halves of the same idea.

Local-first — after Odysseus. Your workspace is yours. Mithra reads your real filesystem from your machine: stdio transport, no network port, no cloud, no data leaving the building (the one exception — a production health-check — is an outbound ping to your own URLs). The command-center has no backend because it doesn't need one.

Related MCP server: jt-mcp-server

Tools

next_actions is the brain: it doesn't just report state, it weighs it. Focus priority dominates; pending work (open tasks, unpushed commits, dirty trees, staleness) breaks ties and surfaces a low-priority project that's quietly piling up. The model gets a decision, not a dashboard to interpret.

Design notes

These were deliberate, and they're the interesting part:

• Read-only by design. The MVP never writes, commits, or touches secrets or prod. Destructive actions belong behind a confirmation step in the GUI, not on an always-available tool surface. An agent with broad write access to your real repos is a footgun; this draws the line on purpose.

• stdio transport, no network port. The server speaks JSON-RPC over stdio to a local client. Nothing is exposed to the network.

• Errors are visible, never swallowed. If one repo fails to read, the rest still return and the failed one carries an explicit error field. Failures surface; they don't hide behind an empty result.

• Pure data layer. All workspace logic lives in lib.js with zero MCP coupling, so it's testable without standing up a server (npm run smoke).

Where this is going

The destination, no hedging: a local-first agent that holds an entire one-person operation in a memory small enough to reason over, retrieving live truth on demand instead of hoarding stale context. Concretely, next:

• Writes behind confirmation. commit_and_push, create_task, move_card — mutations the model can propose and you approve in one step, never an always-on write surface.

• More state, same shape. CI status, error budgets, calendar, inbox — anything that answers "what needs me right now" becomes another read-only tool.

• The memory loop closes itself. The working-memory snapshot stops being hand-curated: the agent proposes what to promote, demote, and forget, with you as the editor.

• The GUI and the tools converge. Mithra already has a GUI embedding the real Claude CLI (node-pty + xterm.js + WebSockets); these tools become how it thinks, not just what it shows.

Run it

npm install
npm run smoke   # verifies the data layer against your workspace
npm start       # starts the MCP server on stdio

By default it reads the parent directory as the workspace root. Override with MITHRA_DOCS=/path/to/workspace.

Private projects. Drop a projects.local.json next to lib.js (gitignored) to track repos you don't want in version control — its entries merge into the default list at startup. See projects.local.example.json for the shape.

Wire it into an MCP client

claude_desktop_config.json (or any MCP client config):

{
  "mcpServers": {
    "mithra": {
      "command": "node",
      "args": ["C:\\path\\to\\mithra-mcp\\index.js"],
      "env": { "MITHRA_DOCS": "C:\\path\\to\\workspace" }
    }
  }
}

Stack

Node (ESM) · @modelcontextprotocol/sdk · zod. No build step.

Built by Ruiciro Rivera as one piece of Mithra, a local-first agentic command-center on Claude Code — LinkedIn. MIT.