MCPInstructionServer

MCPInstructionServer

一个 TypeScript MCP（Model Context Protocol）服务，供 AI 助手发现和访问结构化 Markdown 指令。

概述

MCPInstructionServer 为 Claude 等 AI 助手提供标准化接口，以访问基于 Markdown 的指令库。将指令整理为 Markdown 文件后，你可以：

• 为 AI 提示词创建一个集中式知识库
• 维护有版本管理的结构化指导文档
• 允许 AI 助手按需搜索和检索特定指令
• 为 AI 辅助任务建立一致的模式

工作原理

该服务会为指定目录及其子目录中的 Markdown 文件建立索引，并将每个文件视为一份指令文档。服务会提取每份文档的标题和首段内容，以创建可搜索的摘要。

AI 助手随后可以：

1. 列出所有可用指令及其摘要
2. 根据 ID 请求特定指令

功能

• 基于文件系统的简单存储：只需将 Markdown 文件放在目录中
• 递归扫描目录：通过分层文件夹结构整理指令
• 路径安全：防止目录遍历，并阻止访问允许目录之外的文件
• 自动提取摘要：提取每份文档的 H1 标题和首段内容
• 支持 Model Context Protocol：兼容实现 MCP 的 AI 助手

前提条件

• Node.js 18+（支持 ESM）
• npm 或 yarn
• 具备 TypeScript 和 Markdown 的基础知识

安装

# Clone the repository
git clone https://github.com/yourusername/MCPInstructionServer.git
cd MCPInstructionServer

# Install dependencies
npm install

# Build the project
npm run build

用法

启动服务

# Start with path to your instructions directory
npm start -- /path/to/instructions

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

创建指令

指令就是扩展名为 .md 的 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.

目录结构示例

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

访问指令

该服务提供两个 MCP 工具：

1. listInstructions

返回所有可用指令的列表，以及它们的 ID 和摘要。

响应示例：

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

接收一个指令 ID，并返回相应指令的完整内容。

请求示例：{ "id": "api/authentication" }

开发

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

# Run tests
npm test

安全注意事项

• 服务会验证所有路径，以防止目录遍历攻击
• 只能访问指定指令目录中的文件
• 不提供写入功能，只允许读取

许可证

MIT

参与贡献

欢迎贡献！欢迎提交 Pull Request。