# 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

```bash
# 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

```bash
# 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:

```markdown
# 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

```bash
# 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.