AI Context MCP

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"
      }
    }
  }
}

服务器将：

1. 自动从GitHub下载
2. 如有需要，请自行构建
3. 使用您指定的 .ai-context 文件夹
4. 提供加载代理、指南和框架的工具

它是如何工作的

“Discovery-First Approach”可以翻译为“发现优先方法”或“以发现为先的方法”。这里，“Discovery”指的是探索、发现新事物或新知识的过程，“First Approach”则意味着在方法论上优先考虑或以这一过程为核心。因此，整个短语可以理解为在进行某项工作或研究时，首先注重探索和发现新事物的方法

服务器嵌入了系统指令，指导AI助手进行：

1. 发现可用资源 首先使用 list_all_resources
2. 阅读工具说明 了解每个资源的目的
3. 选择合适的工具 根据当前的任务
4. 战略性地加载资源 - 根据需要，可为单个或多个

这确保了人工智能助手能够适应您的特定需求 .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 前置元数据（推荐）： img.png\\\`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:` 兼容性。