Mcpinstructionserver

🚀 MCP Instruction Server (MCPInstructionServer)

A TypeScript-based Model Context Protocol (MCP) server for AI assistants to discover and access structured Markdown instructions.

🚀 Quick Start

MCP Instruction Server is a TypeScript-based server that enables AI assistants, such as Claude, to access a centralized Markdown instruction library through a standardized interface. By organizing instructions as Markdown files, you can:

• Create a centralized knowledge base of prompts.
• Maintain versioned, structured guidance documents.
• Allow AI assistants to search for and retrieve specific instructions on demand.
• Establish a consistent pattern for AI-assisted tasks.

🔍 Overview

The MCP Instruction Server allows AI assistants like Claude to access a centralized Markdown instruction library via a standardized interface. By organizing instructions as Markdown files, you can:

• Create a centralized knowledge base of prompts.
• Maintain versioned, structured guidance documents.
• Allow AI assistants to search for and retrieve specific instructions on demand.
• Establish a consistent pattern 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. It extracts the title and the first paragraph of each document to generate a searchable summary.

AI assistants can perform the following actions:

1. List all available instructions and their summaries.
2. Request the ID of a specific instruction.

✨ Features

• Simple File System Storage: Only Markdown files in a directory are required.
• Recursive Directory Scanning: Organize instructions hierarchically.
• Path Security: Prevent directory traversal and access to files outside the allowed directory.
• Automatic Summary Extraction: Extract the H1 title and the first paragraph from each document.
• Model Context Protocol Support: Compatible with AI assistants implementing 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 Examples

Basic Usage

Start the Server

# Start with a specified instruction directory
npm start -- /path/to/instructions

# Or use node directly
node dist/index.js /path/to/instructions

Create Instructions

Instructions are simple Markdown files with a .md extension. Each file should follow this structure:

# Instruction Title

A brief description of the purpose of this instruction. This first paragraph will be used as the summary of the instruction in the list.

## Detailed Information

Additional sections with more detailed information...

## Example

Usage examples, code snippets, etc.

Directory Structure Example

instructions/
├── api/
│   ├── authentication.md
│   └── rate-limiting.md
├── design/
│   ├── color-system.md
│   └── typography.md
└── general/
    ├── code-review.md
    └── git-workflow.md

Access Instructions

The server provides two MCP tools:

1. listInstructions

Returns a list of all available instructions, their IDs, and summaries.

Example response:

id: api/authentication
summary: Authentication API - This document outlines the authentication protocol we use in our system.

id: design/typography
summary: Typography Guide - This guide explains our typography scale and usage rules.

2. readInstruction

Accepts an instruction ID and returns the full content of the corresponding instruction.

Example request: { "id": "api/authentication" }

Advanced Usage

Development

# Run in development mode (auto-restart)
npm run dev -- /path/to/instructions

# Run tests
npm test

⚠️ Security Considerations

• The server validates all paths to prevent directory traversal attacks.
• It can only access files in the specified instruction directory.
• There is no write functionality, only read access is allowed.

📄 License

MIT

🤝 Contribution

Contributions are welcome! Please feel free to submit a Pull Request.