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:

1. List all available instructions with their summaries
2. 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.