MCP Servers + Skills (Direct-Use)

Centrally maintained MCP server installations and a shared skills library. Clients (Cursor, OpenCode, Gemini-CLI, Claude Code) consume these via generated configs.

Quick Start (Generator)

Generate your config directly into the target file:

# Claude Code (in project root)
./scripts/ai-setup.ts claude private > .mcp.json

# Cursor
./scripts/ai-setup.ts cursor coding-home > .cursor/mcp.json

Note: For convenience, symlink ai-setup.ts to your ~/.local/bin/ai-setup.

Layout

~/ai/mcp/
├── servers/    -- built MCP server installations
│   ├── filesystem/                 (npm: @modelcontextprotocol/server-filesystem)
│   ├── obsidian-context-server/    (project context, ADRs, FSDs, tasks)
│   ├── obsidian-notes-server/      (note CRUD, plans)
│   ├── obsidian-portfolio-server/  (portfolio generation)
│   ├── obsidian-mcp-server/        (REST API based, cyanheads)
│   └── skills-server/              (exposes skills/ as MCP tools/prompts)
├── skills/     -- SKILL.md library
│   ├── shared/                     (used by every profile)
│   ├── coding/                     (coding profiles only)
│   ├── private/                    (private profile only)
│   └── work/                       (work profiles only)
└── examples/   -- copy-paste configs per (client × profile)
    ├── README.md
    ├── cursor-private.json
    ├── cursor-coding-home.json
    ├── opencode-private.json
    ├── opencode-coding-home.json
    ├── gemini-private.json
    ├── gemini-coding-home.json
    ├── claude-private.json
    └── claude-coding-home.json

Architecture

Detailed design principles and data flow are documented in docs/ARCHITECTURE.md.

Profiles

• private — homevault context (personal vault, recipes, journaling, portfolio).
• coding-home — personal code projects with vault read-access for project notes.

(Pharma is intentionally not represented here — it has its own self-contained .cursor/ setup in ~/pharma/pharma/.cursor/ and is not migrated.)

Why direct-use, no proxy hub?

Earlier this repo ran mcp-proxy-hub as a systemd service per profile. Removed because:

• Upstream had a Node-incompat bug (unix_dgram socket type) in notifySystemd that crashed whenever WatchdogSec triggered.
• A trailing comma in one profile JSON caused 5610 silent restart-loops with no observability.
• Single point of failure: one bug in the hub took down all profiles.

Direct stdio per client means more duplication across config files, but no daemon to manage, no proxy bug surface, and JSON errors surface immediately with a useful error in the client. The trade-off favors robustness over DRY.

Adding a new MCP server

1. Install/build it under servers/<server-name>/.
2. Add its configuration to SERVERS in scripts/lib/definitions.ts.
3. Add the server name to the relevant PROFILES in the same file.
4. Run the generator to update your client configs.

Adding a new skill

1. Create skills/<profile-dir>/<skill-name>/SKILL.md.
2. Set tools_required in the frontmatter to list the MCP servers the skill needs.
3. The skill becomes available in any profile that includes its parent directory in PROFILES (defined in definitions.ts).