MCPInstructionServer
A TypeScript MCP (Model Context Protocol) server for AI assistants to discover and access structured markdown instructions.
Overview
MCPInstructionServer enables AI assistants like Claude to access a library of markdown-based instructions through a standardized interface. By organizing instructions as markdown files, you can:
- Create a centralized knowledge base for AI prompting
- Maintain versioned, structured guidance documents
- Allow AI assistants to search and retrieve specific instructions on-demand
- Establish consistent patterns for AI-assisted tasks
How It Works
The server indexes markdown files in a specified directory (and its subdirectories), treating each file as an instruction document. The server extracts each document's title and first paragraph to create searchable summaries.
AI assistants can then:
- List all available instructions with their summaries
- Request specific instructions by ID
Features
- Simple filesystem-based storage : Just markdown files in directories
- Recursive directory scanning : Organize instructions in a hierarchical folder structure
- Path security : Prevents directory traversal and access to files outside the allowed directory
- Automatic summary extraction : Pulls the H1 title and first paragraph from each document
- Model Context Protocol support : Compatible with AI assistants that implement MCP
Prerequisites
- Node.js 18+ (for ESM support)
- npm or yarn
- Basic familiarity with TypeScript and markdown
Installation
# Clone the repository
git clone https://github.com/yourusername/MCPInstructionServer.git
cd MCPInstructionServer
# Install dependencies
npm install
# Build the project
npm run build
Usage
Starting the Server
# Start with path to your instructions directory
npm start -- /path/to/instructions
# Or directly with node
node dist/index.js /path/to/instructions
Creating Instructions
Instructions are simply markdown files with the .md extension. Each file should follow this structure:
# Instruction Title
Brief description of this instruction's purpose. This first paragraph will be used as the summary when listing instructions.
## Details
Additional sections with more detailed information...
## Examples
Usage examples, code samples, etc.
Directory Structure Example
instructions/
├── api/
│ ├── authentication.md
│ └── rate-limiting.md
├── design/
│ ├── color-system.md
│ └── typography.md
└── general/
├── code-review.md
└── git-workflow.md
Accessing Instructions
The server provides two MCP tools:
1. listInstructions
Returns a list of all available instructions with their IDs and summaries.
Example response:
id: api/authentication
summary: Authentication API - This document outlines the authentication protocol used in our system.
id: design/typography
summary: Typography Guidelines - This guide explains our typographic scale and usage rules.
2. readInstruction
Takes an instruction ID and returns the full content of the corresponding instruction.
Example request: { "id": "api/authentication" }
Development
# Run in development mode with auto-restart
npm run dev -- /path/to/instructions
# Run tests
npm test
Security Considerations
- The server validates all paths to prevent directory traversal attacks
- Only files within the specified instructions directory can be accessed
- No writing capabilities are provided, only reading is allowed
License
MIT
Contributing
Contributions welcome! Please feel free to submit a Pull Request.
