MCPInstructionServer

What is MCPInstructionServer?

MCPInstructionServer is a TypeScript MCP server that lets AI assistants discover and access structured markdown instructions stored in a local directory. It indexes markdown files, extracts titles and summaries, and provides two MCP tools—listInstructions and readInstruction—for listing available documents and retrieving their full content.

How to use MCPInstructionServer?

Start the server by passing the path to your instructions directory: npm start -- /path/to/instructions or node dist/index.js /path/to/instructions. Instructions are plain .md files with an H1 title and a first‑paragraph summary. The server exposes two MCP tools: listInstructions to see all instruction IDs and summaries, and readInstruction with an id parameter to get the full document.

Key features of MCPInstructionServer

• Simple filesystem‑based storage using markdown files in directories
• Recursive directory scanning for hierarchical organization
• Path security prevents directory traversal and access outside the allowed directory
• Automatic extraction of H1 title and first paragraph as summaries
• Model Context Protocol support for compatible AI assistants

Use cases of MCPInstructionServer

• Provide an AI assistant with a centralized, versioned library of prompting guidelines.
• Let Claude or other MCP‑compatible AIs search and retrieve specific instruction documents on demand.
• Establish consistent, structured markdown guidance for AI‑assisted tasks across a team.
• Maintain separate instruction sets (e.g., authentication, design, code review) in a folder hierarchy.

FAQ from MCPInstructionServer

What runtime does MCPInstructionServer require?

Node.js 18+ (for ESM support) and npm or yarn.

How are instructions stored and organized?

Instructions are simply .md files in a specified directory. The server scans recursively, so you can nest files in folders. Each file must have an H1 title and a first paragraph used as the summary.

Is there any writing capability?

No. MCPInstructionServer only provides read‑only access. It has no tools for creating, editing, or deleting files.

How does the server handle security?

It validates all requested paths to prevent directory traversal attacks and ensures only files within the specified instructions directory can be read.

Which MCP tools does the server provide?

Two tools: listInstructions (returns a list of document IDs and their summaries) and readInstruction (requires an id string and returns the full markdown content).