aman-mcp

The MCP server for the aman ecosystem.

Exposes identity, tools, workflows, guardrails, and evaluation as MCP tools — so any AI agent can read and write your ecosystem programmatically.

Setup · Tools · Architecture · Ecosystem

How It Works

┌─────────────────────────────────────────────┐
│              AI Agent / LLM                 │
│         (Claude, GPT, Cursor, etc.)         │
└──────────────────┬──────────────────────────┘
                   │ MCP Protocol
        ┌──────────┴──────────┐
        │     aman-mcp        │  ← this server
        │  11 tools across    │
        │  5 ecosystem layers │
        └──┬──┬──┬──┬──┬─────┘
           │  │  │  │  │
     ┌─────┘  │  │  │  └─────┐
     ▼        ▼  ▼  ▼        ▼
  acore    akit aflow arules aeval
 identity tools flows guards  eval

amem (memory) runs as its own MCP server — see amem.

Setup

One-liner:

claude mcp add aman -- npx -y @aman_asmuei/aman-mcp

Or manually add to ~/.claude/settings.json:

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

Add to .cursor/mcp.json:

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

Add to ~/.codeium/windsurf/mcp_config.json:

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

aman-mcp speaks standard Model Context Protocol over stdio:

npx @aman_asmuei/aman-mcp

Tools

Identity (acore) — ~/.acore/core.md

Tools (akit) — ~/.akit/kit.md

Workflows (aflow) — ~/.aflow/flow.md

Guardrails (arules) — ~/.arules/rules.md

Evaluation (aeval) — ~/.aeval/eval.md

Projects (aprojects) — LRU work-thread tracker

Discrete arcs of work, LRU-positioned across 10 active slots, peer to intentions / eval / rules. Active project surfaces unconditionally in SessionStart.

Storage: ~/.aprojects/dev/plugin/projects.md (single file via MarkdownFileStorage; matches intentions pattern).

Tools:

• project_add — create at #1, shift others, evict at #11

• project_get — read one

• project_list — filter by status / inActiveList

• project_active — fast path: position #1

• project_load — fuzzy match, restore from off-list

• project_touch — bump in-list project to #1

• project_save — append timestamped session note

• project_close — transition to complete / paused / abandoned

• project_update — patch metadata; reciprocally updates intentions.linkedProjectId

Lifecycle vs LRU: orthogonal axes. status is lifecycle (active/paused/complete/abandoned). inActiveList is LRU membership. LRU eviction at #11 sets inActiveList=false but keeps status=active — the project is still alive, just not in the top 10.

Bidirectional link: Setting linkedIntentionId on a project also sets linkedProjectId on the intention (and vice versa). Closing one side does NOT close the other.

Override paths root: $AMAN_PROJECTS_HOME (used by tests).

Architecture

src/
├── index.ts        Entry point — server setup, transport
├── tools/          MCP tool definitions per layer
├── parsers/        Markdown file parsers
└── utils/          Shared utilities

File Locations

The server reads and writes the same files as the CLI tools:

Development

git clone https://github.com/amanasmuei/aman-mcp.git
cd aman-mcp
npm install
npm run build
npm run lint
npm test

The Ecosystem

aman
├── acore      → identity    → who your AI IS
├── amem       → memory      → what your AI KNOWS
├── akit       → tools       → what your AI CAN DO
├── aflow      → workflows   → HOW your AI works
├── arules     → guardrails  → what your AI WON'T do
├── aeval      → evaluation  → how GOOD your AI is
└── aman-mcp   → MCP server  → the bridge  ← YOU ARE HERE

Contributing

Contributions welcome! Open an issue or submit a PR.

License

MIT

11 tools. 5 layers. One MCP server.