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.

MCPInstructionServer