AI上下文MCP服务器
一个独立的MCP（模型上下文协议）服务器，为任何项目提供人工智能上下文编排功能 .ai-context 文件夹。此服务器独立运行，多个项目无需安装即可使用 npx.
快速入门
重要该 AI_CONTEXT_ROOT 需要设置环境变量，并且必须指向您的 .ai-context 文件夹。
光标（Cursor）.cursor/mcp.json)：
{
"mcpServers": {
"ai-context": {
"command": "npx",
"args": ["--yes", "github:alonlevyshavit/ai-context-mcp"],
"env": {
"AI_CONTEXT_ROOT": "/absolute/path/to/your/project/.ai-context"
}
}
}
}Claude Desktop（桌面版）
{
"mcpServers": {
"ai-context": {
"command": "npx",
"args": ["--yes", "github:alonlevyshavit/ai-context-mcp"],
"env": {
"AI_CONTEXT_ROOT": "/absolute/path/to/your/project/.ai-context"
}
}
}
}服务器将：
- 自动从GitHub下载
- 如有需要，请自行构建
- 使用您指定的
.ai-context文件夹 - 提供加载代理、指南和框架的工具
它是如何工作的
“Discovery-First Approach”可以翻译为“发现优先方法”或“以发现为先的方法”。这里，“Discovery”指的是探索、发现新事物或新知识的过程，“First Approach”则意味着在方法论上优先考虑或以这一过程为核心。因此，整个短语可以理解为在进行某项工作或研究时，首先注重探索和发现新事物的方法
服务器嵌入了系统指令，指导AI助手进行：
- 发现可用资源 首先使用
list_all_resources - 阅读工具说明 了解每个资源的目的
- 选择合适的工具 根据当前的任务
- 战略性地加载资源 - 根据需要，可为单个或多个
这确保了人工智能助手能够适应您的特定需求 .ai-context 关注结构，而非假定某些特定因素的存在。
动态工具生成
服务器会自动扫描您的 .ai-context 文件夹，并为每个资源创建特定的MCP工具：
.ai-context/agents/planner.md → load_planner_agent tool
.ai-context/guidelines/api-design.md → load_guideline_api_design tool
.ai-context/frameworks/memory/README.md → load_framework_memory tool每个工具都包含了从资源文件中提取的丰富元数据，以帮助人工智能助手在何时使用这些工具时做出明智的决策。
多格式元数据支持
服务器支持多种元数据格式，并具备优雅的回退机制：
YAML 前置元数据（推荐）： \\\`markdown
描述：任务分解与项目组织的规划专家 用例：
- 将复杂任务分解为更小的步骤
- 制定项目路线图
- 将工作分成可管理的小块
______________________________________________________________________
规划代理
\[内容...\]
**HTML Comments:**Planner Agent
[content...]
**自然语言回退（或：默认自然语言处理）**
Planner Agent
You are a planning specialist focused on breaking down complex tasks into manageable steps. You excel at creating structured roadmaps and organizing work efficiently. [content...]
### 光标配置
创建一个 `.cursor/mcp.json` 在项目根目录中找到文件：
{ "mcpServers": { "ai-context": { "command": "npx", "args": ["--yes", "github:alonlevyshavit/ai-context-mcp"], "env": { "AI_CONTEXT_ROOT": "/absolute/path/to/your/project/.ai-context" } } } }
**注**替换 `/absolute/path/to/your/project/.ai-context` （请提供）您实际的绝对路径 `.ai-context` 文件夹。
### 所需配置
这个（或“该”） `AI_CONTEXT_ROOT` 环境变量必须设置为您的绝对路径 `.ai-context` 文件夹。
这种明确的配置确保：
- 清晰且可预测的行为
- 关于哪一个，没有歧义 `.ai-context` 文件夹正在被使用中
- 在不同环境中保持一致的操作
- 对正在加载的上下文进行明确控制
## 项目结构
your-project/ ├── .ai-context/ # Your AI context directory │ ├── agents/ # Agent definitions (.md files) │ ├── guidelines/ # Guidelines (.md files, can be nested) │ └── frameworks/ # Framework folders with README.md ├── .cursor/ │ └── mcp.json # MCP server configuration └── [your project files...]
## 可用工具
服务器同时提供 **动态的** 和 **静态** 工具：
### 动态工具（根据内容生成）
- `load_[name]_agent` - 加载特定的代理（例如。， `load_debugger_agent`， `load_planner_agent`)
- `load_guideline_[path]` - 加载特定指南
- `load_framework_[name]` - 加载一个框架的文档
### 静态工具（始终可用）
- `list_all_resources` - 列出所有发现的代理、指南和框架
- `load_multiple_resources` - 同时加载多个资源
## 配置选项
### 要求：AI_CONTEXT_ROOT 路径
{ "mcpServers": { "ai-context": { "command": "npx", "args": ["--yes", "github:alonlevyshavit/ai-context-mcp"], "env": { "AI_CONTEXT_ROOT": "/absolute/path/to/.ai-context" } } } }
### 选择性资源加载
通过设置环境变量来控制加载哪些类型的资源作为工具。
**默认行为：**
- **代理；经纪人**始终加载（无法禁用）
- **指南/指导方针**默认禁用（需主动选择启用） `AI_CONTEXT_LOAD_GUIDELINES="true"`)
- **框架**默认禁用（如需启用，请选择 `AI_CONTEXT_LOAD_FRAMEWORKS="true"`)
{ "mcpServers": { "ai-context": { "command": "npx", "args": ["--yes", "github:alonlevyshavit/ai-context-mcp"], "env": { "AI_CONTEXT_ROOT": "/absolute/path/to/.ai-context" // Agents are always loaded // Guidelines and frameworks are disabled by default } } } }
**示例：**
仅加载代理（默认行为）：
"env": { "AI_CONTEXT_ROOT": "/absolute/path/to/.ai-context" }
加载代理和指南：
"env": { "AI_CONTEXT_ROOT": "/absolute/path/to/.ai-context", "AI_CONTEXT_LOAD_GUIDELINES": "true" }
加载所有资源（代理、指南和框架）：
"env": { "AI_CONTEXT_ROOT": "/absolute/path/to/.ai-context", "AI_CONTEXT_LOAD_GUIDELINES": "true", "AI_CONTEXT_LOAD_FRAMEWORKS": "true" }
### 特定版本/分支
{ "mcpServers": { "ai-context": { "command": "npx", "args": ["github:your-org/ai-context-mcp#v1.0.0"] } } }
## 发展
### 设置
git clone https://github.com/your-org/ai-context-mcp.git cd ai-context-mcp npm install
### 命令
npm run build # Build TypeScript to JavaScript npm run dev # Run in development mode npm run test # Run tests npm run test:coverage # Run tests with coverage npm run typecheck # TypeScript type checking npm run validate # Validate .ai-context metadata
### 使用本地项目进行测试
AI_CONTEXT_ROOT=/path/to/test-project/.ai-context npm run dev
## 建筑学
该服务器构建于：
- **TypeScript** 使用ES2022/Node16模块
- **MCP SDK（MCP软件开发工具包）** 用于协议通信
- **Vitest（注：Vitest是一个用于JavaScript/TypeScript项目的轻量级测试框架，此处直接保留原英文名称，因其在技术领域为专有名词）** 进行全面测试（覆盖率98%以上）
- **动态工具生成** 来自文件系统扫描
- **基于枚举的常量** 为了可维护的代码
- **全面的错误处理** 以及记录（日志）
关键部件：
- `Scanner` - 从资源中发现并提取元数据
- `Loader` - 加载内容并组装上下文
- `MetadataExtractor` - 多格式元数据提取，带回退机制
- `AiContextMCPServer` - 主MCP服务器，具备动态工具生成功能
## 许可证
麻省理工学院（MIT）- 详情请参阅LICENSE文件
## 贡献；做出贡献
1. 为仓库创建分支（或：克隆仓库）
1. 创建一个特性分支
1. 在进行更改时进行测试
1. 跑 `npm run test:run && npm run typecheck`
1. 提交一个拉取请求
这个（或“该”） `dist/` 文件夹必须被提交以供（使用/处理/等，具体根据上下文确定） `npx github:` 兼容性。