# User Context MCP Server

A local **stdio Model Context Protocol (MCP) server** that exposes a developer's local context (communication preferences, development stack, active repositories, memory models) to AI agents.

This allows agentic workflows (such as subagents or orchestrators) to bootstrap themselves with local guidelines and environment facts, minimizing context hallucination.

## Features

- Exposes context sections as MCP tools and resources.
- Provides a subagent bootstrap helper tool.
- Supports externalizing context data via the `USER_CONTEXT_ROOT` environment variable.

---

## Setup

### 1. Clone & Install Dependencies

```bash
git clone https://github.com/yourusername/user-context-mcp.git
cd user-context-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 2. Configure Your Personal Context

The repository contains generic template files under `context/`. Copy them to create your active, ignored personal context files:

```bash
cp context/communication.md.example context/communication.md
cp context/memory-model.md.example context/memory-model.md
cp context/repos.md.example context/repos.md
cp context/stack.md.example context/stack.md
```

Then edit the `.md` files to match your local setup. These files are listed in `.gitignore` so they won't be committed to your repository.

> [!TIP]
> Alternatively, you can keep your active context files in a private directory completely outside the repository by setting the `USER_CONTEXT_ROOT` environment variable:
> ```bash
> export USER_CONTEXT_ROOT="$HOME/.config/user-context"
> ```

### 3. Inspect and Run the Server

You can inspect the server tools and call them locally using `fastmcp`:

```bash
fastmcp inspect server.py:mcp
fastmcp call server.py get_context section=stack --json
```

---

## Integration with Agentic Systems (e.g. Hermes)

You can register this MCP server with your local agent client or shell extension (such as Hermes).

For Hermes, register using the stdio transport:

```bash
# Register (interactive — pipe y to auto-accept):
printf 'y\n' | hermes mcp add user_context \
  --command /path/to/user-context-mcp/.venv/bin/python \
  --args /path/to/user-context-mcp/server.py
```

*Note: Replace `/path/to/user-context-mcp` with the absolute path to your cloned repository.*

Start a **new session** (or run `/reload-mcp` + `/reset`) so the tools load. Tools will appear with the `mcp_user_context_` prefix (e.g., `mcp_user_context_get_context`).

---

## Tools

| Tool | Purpose |
|------|---------|
| `list_context_sections` | List available context sections and check whether files exist on disk. |
| `get_context` | Retrieve the markdown content of a specific section (or `full` to concatenate all). |
| `get_delegation_bootstrap`| Get bootstrap instructions suitable for pasting into subagent contexts. |

## Resources

- `user-context://communication`
- `user-context://stack`
- `user-context://repos`
- `user-context://memory-model`
- `user-context://full`

---

## Optional: Syncing to Hermes Skill

If you use Hermes' local skill directory to cache delegation contexts, you can sync your edits using the included helper script:

```bash
.venv/bin/python scripts/sync_to_hermes_skill.py --dry-run
```

By default, this writes to `~/.hermes/skills/software-development/delegation-user-context/SKILL.md`.

---

## HTTP Transport (Optional)

To run the server as an HTTP service:

```bash
fastmcp run server.py:mcp --transport http --host 127.0.0.1 --port 8765
```