aman-mcp

<div align="center">

<br>

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/aman--mcp-MCP_server-white?style=for-the-badge&labelColor=0d1117&color=58a6ff"> <img alt="aman-mcp" src="https://img.shields.io/badge/aman--mcp-MCP_server-black?style=for-the-badge&labelColor=f6f8fa&color=24292f"> </picture>

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.

<br>

Setup · Tools · Architecture · Ecosystem

</div>

---

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

<details> <summary><strong>Claude Code</strong></summary>

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"]
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json:

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

</details>

<details> <summary><strong>Windsurf</strong></summary>

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

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

</details>

<details> <summary><strong>Any other MCP client</strong></summary>

aman-mcp speaks standard Model Context Protocol over stdio:

npx @aman_asmuei/aman-mcp

</details>

---

Tools

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

Tool	Description
identity_read	Read the full core.md identity file
identity_summary	Get structured summary: AI name, user name, trust level, personality
identity_update_session	Update the Session section (resume, topics, decisions)

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

Tool	Description
tools_list	List all installed tools with status
tools_search	Search tool registry by query

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

Tool	Description
workflow_list	List all defined workflows
workflow_get	Get a specific workflow's steps

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

Tool	Description
rules_list	List all rule categories
rules_check	Check if an action violates any rules

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

Tool	Description
eval_status	Get evaluation metrics (sessions, trust, trajectory)
eval_log	Log a session with rating and notes

---

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:

File	Layer
~/.acore/core.md	Identity and personality
~/.akit/kit.md	Tool registry
~/.aflow/flow.md	Workflow definitions
~/.arules/rules.md	Guardrail rules
~/.aeval/eval.md	Evaluation log

---

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

Layer	Package	What it does
Identity	acore	Personality, values, relationship memory
Memory	amem	Automated knowledge storage (MCP)
Tools	akit	15 portable AI tools (MCP + manual fallback)
Workflows	aflow	Reusable AI workflows
Guardrails	arules	Safety boundaries and permissions
Evaluation	aeval	Relationship tracking and session logging
Unified	aman	One command to set up everything

---

Contributing

Contributions welcome! Open an issue or submit a PR.

License

MIT

---

<div align="center">

11 tools. 5 layers. One MCP server.

</div>