User Context 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

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:

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:

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:

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:

# 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:

.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:

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