@gramatr/mcp

⚠️ Deprecated

This package is no longer the recommended way to use grāmatr.

Install the Claude Code plugin instead:

/plugin marketplace add gramatr/claude-plugin
/plugin install gramatr@gramatr-claude-plugin

The plugin handles OAuth automatically through Claude Code’s connector flow — no manual setup, no local installer side-effects.

Codex and Gemini integrations are paused while those clients lack HTTPS+OAuth MCP support. We’ll revisit when they’re ready.

See: https://github.com/gramatr/gramatr/issues/2750

Intelligence middleware for AI agents by gramatr.

Pre-classifies every request, injects relevant memory and behavioral context, enforces data quality, and maintains session continuity across Claude, ChatGPT, Codex, Cursor, Gemini, and any MCP-compatible client.

Quick Install (Claude Code)

npx @gramatr/mcp install

Idempotent. Safe to re-run for upgrades. Configures everything in one shot:

1. Auth check — runs device-flow login if ~/.gramatr.json has no token.
2. Hook script — drops ~/.gramatr/scripts/hook-userpromptsubmit.sh (chmod 0755).
3. Settings merge — adds the UserPromptSubmit entry to ~/.claude/settings.json, preserving every other key. Backs up to ~/.claude/settings.json.bak-<ts> first.
4. CLAUDE.md merge — upserts the gramatr agent contract between <!-- GRAMATR-START --> / <!-- GRAMATR-END --> sentinels in ~/.claude/CLAUDE.md. Preserves everything outside the block.
5. Legacy cleanup — on by default (v0.20.6+). Removes the legacy 14-handler scaffold (~/.gramatr/bin/gramatr-hook*), daemon state.db*, ~/.gramatr/debug/, stale auth-cache backups, and legacy gramatr-flavored slash commands under ~/.claude/commands/ (e.g. save-handoff.md that still references the retired ~/.gramatr/.state/last-packet.json path). Stale grāmatr-tagged hook entries in ~/.claude/settings.json are stripped before the canonical set is re-added. Pass --keep-legacy to preserve them.
6. Project settings sweep — strips any grāmatr-owned hook entries from <cwd>/.claude/settings.json (grāmatr hooks belong in user-level config only). Does not add hooks here.
7. Pre-authorization prompt — interactively asks whether to pre-allow grāmatr MCP tools in permissions.allow (None / Read / All). Skip the prompt with --pre-auth=<tier> or --non-interactive.

Restart Claude Code after install to activate the hook.

Flags

Flag	Effect
--client=<claude-code|claude-desktop|claude-web>	Target a specific client. Default: auto-detect.
--keep-legacy	Preserve legacy gramatr-* hook entries instead of stripping them. Default behaviour (v0.20.6+) is clean-on.
--pre-auth=<none|read|all>	Pre-authorize grāmatr MCP tools in permissions.allow. Skips the interactive prompt.
--non-interactive	CI-friendly; no interactive prompts. Pre-auth defaults to none unless --pre-auth is set.
--dry-run	Print actions without writing.

Multi-client install (#2472)

Client	Behavior
claude-code	Full path: hook scripts + ~/.claude/settings.json + ~/.claude/CLAUDE.md. Auto-detected when ~/.claude/settings.json exists or ~/.claude.json has mcpServers.
claude-desktop	Writes a gramatr entry into claude_desktop_config.json (HTTP transport + Bearer header from ~/.gramatr.json). No shell hooks. Auto-detected when the Desktop config exists at the platform path (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/). Restart Claude Desktop after install.
claude-web	No filesystem changes. Prints copy-paste connector setup steps (URL, OAuth/API key flow) and the canonical prompt suggestion to paste into claude.ai → Settings → Profile → Custom Instructions.

Uninstall

npx @gramatr/mcp uninstall          # remove hook + CLAUDE.md section, keep token
npx @gramatr/mcp uninstall --purge  # also remove ~/.gramatr.json

Every file is backed up before mutation.

Setup Targets (other clients)

gramatr setup claude           # Claude Code (hooks + MCP + guidance)
gramatr setup codex            # OpenAI Codex (hooks + guidance)
gramatr setup claude-desktop   # Claude Desktop app (MCP config)
gramatr setup chatgpt-desktop  # ChatGPT Desktop app (MCP config)
gramatr setup gemini           # Gemini CLI (extension + hooks)
gramatr setup web              # Claude.ai web (instructions + prompt)
gramatr setup web chatgpt      # ChatGPT web connector
gramatr setup web gemini       # Gemini web connector

Authentication

gramatr login          # Browser-based OAuth login
gramatr add-api-key    # Store an API key directly
gramatr logout         # Remove stored credentials

Credentials are stored in ~/.gramatr.json. The MCP server reads the token on startup and injects it into every remote call.

How It Works

Your AI client (Claude, Cursor, Codex, ...)
    |
    stdio
    |
@gramatr/mcp (local, runs on your machine)
    |
    HTTPS (authenticated)
    |
api.gramatr.com (hosted intelligence layer)

The local server:

• Proxies all remote tools — fetches the tool list dynamically at startup, no hardcoded tool names
• Proxies prompts and resources — server-defined prompt templates available locally
• Validates input — JSON Schema validation + entity type enforcement before calls leave your machine
• Caches reads — LRU cache (100 entries, 60s TTL) for read-only tools
• Queues mutations offline — network drops don’t lose writes; replayed on reconnect
• Runs hooks — session-start, prompt routing, input validation, tool tracking, rating capture, classification feedback, session-end
• Local tools — web fetch, web search, status, metrics, cache management

Local Tools

Tool	Purpose
gramatr_local_status	Server health, uptime, tool counts, cache stats
gramatr_local_metrics	Per-tool latency (p50/p95/p99), cache hit rate
gramatr_local_config	Auth source, server URL, cache settings
gramatr_local_clear_cache	Flush LRU cache
gramatr_local_fetch	Fetch any URL, strip HTML, return text
gramatr_local_search	DuckDuckGo web search (no API key needed)

Debug Mode

GRAMATR_DEBUG=1 claude

Logs every JSON-RPC request/response and routing decision to stderr. Auth tokens are redacted.

MCP Client Configuration

For clients that support MCP natively, add this to your MCP config:

{
  "mcpServers": {
    "gramatr": {
      "command": "node",
      "args": ["~/.gramatr/mcp/dist/bin/gramatr-mcp.js"]
    }
  }
}

Or via npx (slower, checks npm on every start):

{
  "mcpServers": {
    "gramatr": {
      "command": "npx",
      "args": ["-y", "@gramatr/mcp"]
    }
  }
}

State Files

Path	Purpose
~/.gramatr.json	Auth token + server URL
~/.gramatr/settings.json	Identity, principal config
<project>/.gramatr/settings.json	Per-project config (project UUID, session state)
~/.gramatr/.state/	Session runtime (turns, metrics, op history)

Requirements

• Node.js >= 20
• A gramatr account (sign up at gramatr.com)

License

See LICENSE in this package.