mcp-instructions-server
A minimal, production-ready Model Context Protocol (MCP) server in Python that provides canonical instructions to any MCP-capable AI application.
Installation
Ensure you have Python 3.10+ installed. Then install the package:```bash
pip install -e .
Or using pip directly:```bash
pip install .
Running the Server
Development Mode```bash
python -m mcp_instructions_server.server
Or using the dev script (after installation):```bash
dev
Production Mode```bash
start
## Development Scripts
- `dev` - Run the server in development mode
- `start` - Start the server in production mode
- `lint` - Run linting checks using ruff
- `format` - Format code using ruff formatter
## Example MCP Client Usage
### Fetching Prompts
The server provides three prompts:
1. **security** - Security instruction for enforcing least privilege and security best practices
2. **rai_guidance** - Responsible AI (RAI) guidance for ethical AI practices
3. **all_instructions** - Combined security and RAI guidance instructions
Example using an MCP client:```python
# Example: Fetching the security prompt
# The client would call the MCP prompt API to get:
# {
# "role": "system",
# "content": "Enforce least privilege, redact secrets, refuse exploit/abuse content, validate untrusted inputs, prefer most restrictive rule on conflict."
# }
Fetching Resources
The server exposes one resource:
- instructions://canonical - Complete canonical instructions in Markdown format
Example:```python
The client would call the MCP resource API to fetch:
URI: instructions://canonical
MIME Type: text/markdown
Content: Markdown with version header and both Security and RAI Guidance sections
### Health Check Tool
The server provides a `health_check` tool that returns server status:```python
# Example response:
{
"status": "ok",
"serverTime": "2024-01-01T12:00:00.000000Z"
}
Example Cursor Configuration
To integrate the mcp-instructions-server with Cursor, add the following to your Cursor configuration:```json
{
"mcpServers": {
"instructions": {
"command": "python",
"args": ["-m", "mcp_instructions_server.server"]
}
}
}
**Note**: Adjust the path to Python as needed. If you've installed the package in a virtual environment, you may need to use the full path to the Python executable.
## Acceptance Checks
### Prompts Panel
Verify that the prompts panel displays:
- `security`
- `rai_guidance`
- `all_instructions`
### Resource Fetch
Ensure that fetching the `instructions://canonical` resource returns:
- Markdown content with both Security and RAI Guidance sections
- Version header: `# Instructions Version v1.0.0`
### Health Check
Confirm that calling `health_check` returns:
- `{"status": "ok", "serverTime": ""}`
## Project Structure```
mcp_instructions_server/
├── __init__.py # Package initialization
├── server.py # Main entrypoint; registers prompts, resources, tools
├── instructions.py # Stores versioned instruction text
├── prompts.py # Wires MCP prompts
├── resources.py # Wires MCP resources
└── tools.py # Defines health_check tool
Quality Assurance
- Code Quality: Clean, well-documented code with no TODOs
- Type Hints: Full type annotations throughout
- Logging: Structured logging with graceful shutdown handling
- Linting: Run
lintto check code quality - Formatting: Run
formatto format code
Updating Instructions
To update the instruction content, edit mcp_instructions_server/instructions.py:
- Update
INSTRUCTIONS_VERSIONas needed - Modify
SECURITY_INSTRUCTIONfor security guidelines - Modify
RAI_GUIDANCEfor RAI guidance - The
ALL_INSTRUCTIONS_MDwill automatically include both sections
License
MIT
