# instruction-mcp
A minimal MCP server that serves markdown instructions as tools.
## Why?
LLMs work better with context. Instead of copy-pasting instructions into every conversation, define them once and deliver them to all your LLM applications — Claude Desktop, Claude Code, and any MCP-compatible client.
**Use cases:**
- **Team playbooks** — Coding standards, review checklists, incident response
- **Domain knowledge** — Data dictionaries, API conventions, business rules
- **Personal workflows** — Analysis templates, writing guides, debugging steps
No UI, no database — just a YAML config and markdown files. Version control your instructions with git, share them across your team.
## How It Works
1. Define tools in `instruction.yaml` pointing to markdown files
2. Run the MCP server
3. Claude sees your tools and calls them based on conversation context
4. Tool returns the markdown content
5. Claude uses the instructions to help with your task
## Understanding Tool Behavior
**Tool descriptions determine when Claude calls the tool.** Claude reads all available tool descriptions and picks the relevant one based on your prompt.
**Tool responses are context, not commands.** When a tool returns markdown, it's added to the conversation like any other text. Claude doesn't automatically "follow" it — your prompt determines that.
### Retrieval vs Action
```
# Just retrieves and summarizes
"What's our code review process?"
# Retrieves AND follows the instructions
"Review this PR following our code review process"
```
The word "following" makes Claude apply the instructions rather than just report them.
### Being Explicit
For guaranteed results, name the tool directly:
```
"Use get_code_review to review this PR and follow the checklist"
```
This ensures:
1. The tool is called (no relying on description matching)
2. The instructions are followed (not just retrieved)
## Quick Start
### 1. Create your config
```yaml
# instruction.yaml
version: "1"
tools:
get_coding_standards:
title: "Coding Standards"
description: "Team coding standards and best practices"
default: "general"
instructions:
general: "resources/standards/general.md"
typescript: "resources/standards/typescript.md"
testing: "resources/standards/testing.md"
```
### 2. Add your markdown files
```
my-instructions/
├── instruction.yaml
└── resources/
└── standards/
├── general.md
├── typescript.md
└── testing.md
```
### 3. Validate
```bash
npx instruction-mcp validate -c instruction.yaml
```
### 4. Add to Claude Desktop
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"my-instructions": {
"command": "npx",
"args": ["instruction-mcp", "-c", "instruction.yaml"],
"cwd": "/absolute/path/to/my-instructions"
}
}
}
```
### 5. Use in Claude
> "Review this PR for me"
Claude will call `get_coding_standards` and use your team's standards to review the code.
## CLI
```bash
# Validate config and check all files exist
npx instruction-mcp validate -c instruction.yaml
# List all tools and instructions
npx instruction-mcp list -c instruction.yaml
# Start server (stdio mode)
npx instruction-mcp -c instruction.yaml
```
## Config Reference
```yaml
version: "1"
tools:
tool_name: # Tool name exposed to Claude
title: "Human Title" # Display name
description: "..." # Helps Claude decide when to use this tool
default: "key" # Optional: default if no instruction specified
instructions:
key1: "path/to/file.md" # Instruction key -> markdown file
key2: "path/to/other.md"
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | yes | Human-readable tool name |
| `description` | string | yes | Description for Claude's tool selection |
| `default` | string | no | Default instruction key |
| `instructions` | map | yes | Key-value pairs of name: filepath |
## Example
See [`example/`](./example) for a complete working setup with analyst playbooks and code review checklists, including Docker deployment.
## License
MIT
