AI导哈

AI上下文编排服务器

一个独立的MCP服务器，为带有.ai-context文件夹的项目提供AI上下文编排服务，支持动态工具生成和多格式元数据。

  • by alonlevyshavit
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 alonlevyshavit/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 前置元数据（推荐）： ```markdown

描述：任务分解与项目组织的规划专家 用例：

  • 将复杂任务分解为更小的步骤
  • 制定项目路线图
  • 将工作分成可管理的小块

规划代理

[内容...]


**HTML Comments:**
```markdown
<!-- metadata
description: Planning specialist for task breakdown and project organization
use_cases: Task breakdown; Project roadmaps; Work organization
-->
# 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. 为仓库创建分支（或：克隆仓库）
  2. 创建一个特性分支
  3. 在进行更改时进行测试
  4. 跑 npm run test:run && npm run typecheck
  5. 提交一个拉取请求

这个（或“该”） dist/ 文件夹必须被提交以供（使用/处理/等，具体根据上下文确定） npx github: 兼容性。

相关 MCP