StarterKit MCP AgenticRAG Copilot

规格驱动的代理式Web启动器（Copilot + Ollama RAG）

确定性、人为触发的规格（spec）工作流程，专为……定制 GitHub Copilot (聊天) 和一个 本地RAG（检索增强生成） 栈（stack）

• 后端： FastAPI
• RAG：（通常指）检索增强生成（Retrieval-Augmented Generation） Ollama（生成+嵌入）+ ChromaDB（本地向量存储）
• 前端： React（Vite）
• 测试： Pytest（后端），Vitest + RTL（前端）
• CI：（此处“CI”可能代表多种含义，具体需根据上下文确定，如“公司识别”、“色彩识别”等，但直接翻译为中文时，通常保持原样或根据具体语境翻译） GitHub Actions

快速入门（本地）

1. 安装 Ollama（注：Ollama是一个用于本地运行大型语言模型的工具，此处直接音译，若需具体含义或品牌名翻译，需根据上下文确定） 并拉动模型（优先选择小模型）：

   curl -fsSL https://ollama.com/install.sh | sh   # or follow mac/win installer
   ollama pull llama3.1:8b
   ollama pull nomic-embed-text

1. 后端：

   cd backend
   python -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   uvicorn app.main:app --reload

1. 前端：

   cd ../frontend
   npm install
   npm run dev

1. 在另一个终端中为RAG（检索增强生成）输入文档：

   cd backend && source .venv/bin/activate
   python -m app.rag.ingest ../rag/docs

1. 通过API提出问题：

   curl -s localhost:8000/api/rag/query -X POST -H "Content-Type: application/json"      -d '{"question":"What is this project about?"}'

决定论与审计： 步骤已被锁定 /specs/STEP_*.md所有与Copilot一起使用的提示都应复制到 /docs/PROMPTS.md 并总结在 /docs/AI_ACTIVITY_LOG.md。

代理工作流（确定性工具运行器）

# RAG-answer workflow (no MCP)
cd backend && source .venv/bin/activate
python -m orchestrator.runner --workflow orchestrator/workflows/rag_answer.yaml

## MCP server demo (read-only files)
# Dry-run to validate steps
python -m orchestrator.runner --workflow orchestrator/workflows/fs_read_example.yaml --dry-run

# Execute (runner starts the MCP server command from the workflow)
python -m orchestrator.runner --workflow orchestrator/workflows/fs_read_example.yaml

MCP Python SDK 提供了工具/资源/提示；请参阅其快速入门和概念部分（您将在示例服务器中看到相同的构造）。

对于更多服务器（如GitHub、Slack等），请浏览官方示例和服务器注册表，以集成已知可靠的工具。

可重用的代理规范与模板

A) 工具规范（请放入/docs/TOOLS_SPEC.md或/tools/specs/\*.yaml）

name: rag.query
version: 1.0.0
summary: Ask the local RAG API a question and return answer + sources.
input_schema:
  type: object
  required: [question]
  properties:
    question: { type: string, minLength: 3, maxLength: 2000 }
output_schema:
  type: object
  required: [answer, sources]
  properties:
    answer: { type: string }
    sources:
      type: array
      items:
        type: object
        required: [path, chunk_index]
        properties:
          path: { type: string }
          chunk_index: { type: integer, minimum: 0 }
side_effects: network
security:
  auth: none (local)
errors:
  - code: RAG_EMPTY
    when: no docs in store
  - code: RAG_FAILURE
    when: vector search or generation fails

B) 工作流YAML（每一步使用一个工具，避免意外）

name: rag.answer
steps:
  - use: rag.query
    with:
      question: "What is this project about?"

With MCP tools (strict allow-list)
name: fs_read_example
mcp:
  - server: fileserver
    command: "uv run python mcp_servers/fileserver/server.py"
    tools_allowlist: ["fs.list_dir", "fs.read_text"]
steps:
  - use: mcp:fs.list_dir
    with: { path: "./docs" }
  - use: mcp:fs.read_text
    with: { path: "./docs/AGENT_ARCHITECTURE.md" }

该运行器验证输入，编写后端代码/运行/\_.jsonl 文件格式，如果工具未被列入允许列表或输入不符合模式，则停止执行。

此试剂盒中的MCP

• 服务器：mcp_servers/fileserver/server.py —— 这是一个只读的FastMCP服务器，配备了两个安全工具：fs.list_dir（列出目录）和fs.read_text（读取文本，仅限cap+UTF-8编码）。

• 客户端：backend/orchestrator/mcp_client.py —— 通过标准输入输出连接，列出工具，并调用工作流中允许使用的工具。

• 文档：MCP_OVERVIEW.md 解释了安全态势 + 参考资料。

SDK（软件开发工具包）& 规范： Python SDK实现了“工具/资源/提示”以及全面的协议支持（stdio/SSE/HTTP）。如需在此演示之外进行扩展，请参阅快速入门指南和规范以获取确切的架构/字段信息。

兼容性说明： OpenAI的代理SDK（软件开发工具包）和“连接器/MCP（机器控制协议）”文档描述了导入工具定义时的互操作性和成本语义。如果您/当您将这些工具集成到托管代理框架中时，这些信息将非常有用。

有益的解释（基于检索增强生成技术+自主选择）

• 为什么选择本地RAG（检索增强生成）？ 隐私+速度。使用Ollama同时处理嵌入和生成，以避免不匹配带来的麻烦；使用Chroma作为无需操作的本地向量数据库。

• 为什么采用分步锁定的工作流程？ 零“隐性”自主权 = 避免范围蔓延。你掌控计划；执行者只需执行并记录。

• 何时应选择MCP而非本地工具？

- MCP：当你需要一个标准的、可发现的工具界面，或者想要重用一个已知的服务器（文件系统、GitHub、搜索等）时。

- 本地工具：当事物与特定项目相关，或者你不需要进行发现/传输时使用。

重要的安全与防偏移护栏

• 最小权限原则：仅暴露所需内容；优先选择只读模式（此工具包的示例服务器为只读模式）。

• 白名单：每个MCP工具调用都必须在tools_allowlist中列出名称。

• 速率限制：如果封装远程API，请为每种工具添加配额。

• 清理日志：运行程序记录输入/输出（生产环境中进行截断/个人信息去标识化处理）。

• 保持最新状态：关注协议和服务器的更新（例如，文件服务器的安全修复）并确保您的SDK保持最新版本。

embracethered.com 可以翻译为“拥抱红色（或热情/活力）之网”或根据具体语境调整为更贴切的表达，如“热情拥抱网站”等。不过，由于“embracethered”并非一个广泛认知的英文词汇组合，其翻译可能需要根据网站的具体内容和目的来进一步确定。在这里，我提供了一个较为通用的翻译方向

Copilot 提示片段（粘贴这些）

• 仅使用脚手架

“仅根据/specs/STEP_0X\_\*.md生成框架代码。不包含业务逻辑。输出文件路径和内容。”

• 测试先行

“为（某个功能/模块）编写失败的测试用例 不要执行代码。以“STOP – 测试按设计失败”结尾。”

• “Implement-to-green”可以翻译为“实施以促进绿色（发展/行动）”。不过，这个翻译可能需要根据具体上下文稍作调整，因为“Implement-to-green”本身并不是一个标准的英语短语，其含义可能依赖于特定的语境或行业背景。在这里，“Implement”意为“实施”，“to-green”则可能指的是“为了绿色（目的）”或“促进绿色（发展/行动）”。因此，一个较为通用的翻译是“实施以促进绿色（发展/行动）”

“做出最小的改动以使这些测试通过。不要添加新功能。”

• 工具规格

“创建/tools/specs/使用 /docs/TOOLS_SPEC.md 生成 .yaml 文件（输入/输出模式 + 错误代码）。“

• MCP服务器

“为（某应用/系统）搭建一个只读的FastMCP服务器 ，包含README文件，并且路径/大小有限制。”