A local MCP server that gives AI agents instant, structured access to your Mastery project context. Written in Go. Zero configuration.
Structured queries for project status, features, tasks, test plans, reviews, changelogs, and full-text search.
Raw access to every Mastery document — project context, roadmap, discussion, features, compact variant, AGENTS.md, llms.txt.
Walks up from the working directory to find docs/mastery.md — like Git finding .git/. Zero config needed.
When AI agents work on Mastery projects, they need to understand project context — the roadmap, current feature, active tasks, architecture decisions, and session history. Without an MCP server, agents read 5+ markdown files, parse tables mentally, and often get confused about what's current.
Agent: *reads project-context.md*
Agent: *reads project-roadmap.md*
Agent: *reads tasks.md, changelog.md, discussion.md...*
Agent: *tries to figure out which feature is active...*
Agent: "I think you're working on Feature #04, task 3.2?"Agent: *calls get_session_context()*
Agent: "You're on Feature #04 (User Auth), task 3.2 (JWT validation).
Last session ended at checkpoint B. Continuing from there."One call. Instant context. No guessing.
go install github.com/RAiWorks/mastery-mcp-server/cmd/mastery-mcp@latestOr download a pre-built binary from GitHub Releases (Linux, macOS, Windows × amd64/arm64).
Add to your MCP client configuration. The server uses stdio transport — no ports, no HTTP, no auth.
{
"servers": {
"mastery": {
"command": "mastery-mcp",
"args": ["serve"]
}
}
}{
"mcpServers": {
"mastery": {
"command": "mastery-mcp",
"args": ["serve"]
}
}
}{
"mcpServers": {
"mastery": {
"command": "mastery-mcp",
"args": ["serve"]
}
}
}The server auto-discovers your project's docs/ folder by walking up from the working directory. Override with --dir:
mastery-mcp serve --dir /path/to/project14 queryable tools that parse Mastery docs and return structured JSON. AI agents call these for fast, accurate context.
| Tool | Purpose |
|---|---|
get_project_status |
Project name, version, progress %, feature counts |
get_project_context |
Parsed project identity — type, tech stack, architecture, scope |
get_roadmap |
Feature list with statuses, dependencies, milestones |
get_current_feature |
Active in-progress feature details (supports lightweight features) |
get_feature_tasks |
Task list with checkbox states for a specific feature |
get_feature_design |
Architecture/design document for a specific feature |
get_feature_testplan |
Test plan — acceptance criteria, test cases, summary |
get_feature_review |
Post-implementation review — reflections, metrics, follow-ups |
get_feature_api |
API/interface spec — endpoints, methods, auth requirements |
get_feature_discussion |
Feature discussion — summary, decisions, status |
get_session_context |
Everything an agent needs to resume work |
get_recent_decisions |
Latest decisions across all docs |
get_project_changelog |
Shipped versions — added, changed, fixed, removed |
search_docs |
Full-text search across all Mastery docs, AGENTS.md, SKILL.md, llms.txt |
11 raw document resources for when agents need the full file content instead of parsed structures.
| URI | Description |
|---|---|
mastery://mastery |
The Mastery framework — docs/mastery.md (full, ~25k tokens) |
mastery://mastery-compact |
Compact variant — docs/mastery-compact.md (~5k tokens, rules only) |
mastery://project/context |
Project identity, stack, conventions, scope |
mastery://project/roadmap |
Feature list, progress, milestones |
mastery://project/discussion |
Project-level decisions and open questions |
mastery://project/changelog |
Shipped versions (Keep a Changelog format) |
mastery://feature/{number} |
All docs for a feature (concatenated) |
mastery://changelog |
Development CHANGELOG.md |
mastery://overrides |
Process overrides (team customizations) |
mastery://agents |
AGENTS.md — AI agent orientation |
mastery://llms |
llms.txt — machine-readable project summary |
Server starts and walks up from the working directory until it finds docs/mastery.md. That directory becomes the project root.
Markdown files are parsed into structured data — tables become arrays of objects, checkboxes become task lists, blockquotes become metadata.
Tools return parsed JSON via MCP stdio transport. Resources return raw Markdown. File changes trigger automatic notifications.
mastery-mcp serve [--dir <path>] # Start MCP server (stdio)
mastery-mcp status [--dir <path>] # Print project status
mastery-mcp version # Print versiondocs/mastery.md)mastery-mcp-server is MIT licensed, just like the framework. Single binary, no external dependencies at runtime. Built with Go, mcp-go, and goldmark.