Common Tasks MCP

通用DAG MCP服务器

一个基于配置驱动的模型上下文协议（MCP）服务器，用于管理具有灵活关系类型的有向无环图（DAGs）。该服务器用Go语言构建，以确保高性能和类型安全。

概述

这是一个 通用、可重用的有向无环图（DAG）框架 该系统通过MCP（管理控制平面）暴露图操作。服务器的域、术语和关系类型完全由配置驱动——使您能够使用有向关系来建模任务、食谱、服务、基础设施、学习路径或任何其他领域。

关键的建筑原则：

• 零代码域适应通过编辑YAML文件，将“tasks”更改为“recipes”，再更改为“services”
• 多个独立的有向无环图（DAGs）每种关系类型都形成其自身的有向无环图（DAG），并且共享相同的节点
• 配置驱动的工具基于您的域配置，MCP工具及其描述会自动生成
• 运行时类型安全尽管配置灵活，但类型严格
• 自动循环检测确保所有关系有向无环图（DAG）保持有效

该系统通过为人工智能助手提供结构化且可查询的知识图谱，打破了知识孤岛。无论是关于开发工作流程的制度性知识、服务依赖关系、配方关联，还是学习路径，同一框架都能适应您的领域需求。

⚠️ 活跃开发通知 该项目正处于积极开发中。随着设计的演进，API、配置模式和实现细节可能会发生变化。虽然核心概念（DAG管理、配置驱动的领域建模）是稳定的，但具体的接口和文件格式在未来的版本中可能会有所变更。

动机

人工智能助手和代理工作流程越来越需要特定领域的知识才能有效运行。然而，传统方法——将大型文档文件直接输入提示中或期望人工智能解析零散的非结构化知识——效率低下，并且很快就会达到上下文窗口的限制。现代人工智能系统在与（以下内容配合使用时）表现最佳： 小而有针对性的信息片段 在需要时准确送达。

这是结构化知识图谱的卓越之处。无需为人工智能提供长达50页的部署操作手册，你只需让它查询：“部署到生产环境的前提条件是什么？”系统就会返回仅相关的节点及其关系——正是所需的上下文，不多也不少 "less is more" 翻译成中文是“少即是多” 这一原则对于有效的上下文工程至关重要。

有向无环图（DAG）结构提供了语义关系，使人工智能系统能够智能地进行导航。当人工智能助手询问某项任务时，它不仅能获取任务描述，还能了解哪些步骤必须先执行（前置条件）、哪些步骤必须随后执行（必需的后续步骤）以及哪些步骤是建议的（建议的后续步骤）。这使得智能体工作流能够规划多步骤操作，理解依赖关系，并在不超出其上下文窗口容量的情况下做出明智的决策。

常见应用：

• AI代码助手 理解仓库工作流和构建过程
• 代理系统 规划具有依赖关系意识的多步骤操作
• 自动化工具 需要知道工作流程中“接下来是什么”的人
• 知识管理 按需展示机构知识的系统
• 决策支持 导航复杂操作流程的系统

通过将领域知识编码为可查询的图形而非静态文档，该服务器使人工智能系统能够实现更高的精确度、效率以及上下文感知能力。

“Dogfooding”可以翻译为“内部试用产品”或“自我食用（产品）”。这个短语通常用来描述公司或组织在产品正式发布前，让自己的员工或团队先使用该产品，以测试其性能、发现潜在问题或收集反馈意见。这种做法有助于确保产品质量，并提高产品的市场适应性

这个项目利用自身来管理开发工作流程 .tasks/ 目录中包含了我们自己的任务存储库，用于跟踪常见的开发操作，如运行测试、更新文档和审查示例。这既是一个实用的开发工具，也是系统在实际应用中的一个演示。

见 .tasks/README.md（文件名，可译为“任务/README.md”或保持原样，因为文件名通常不翻译） 用于获取设置说明和使用示例。

特点/特性

• 配置驱动的身份服务器名称、术语和工具名称可根据您的领域进行调整
• 灵活的关系系统定义具有时间方向性的无限关系类型
• 多个独立的有向无环图（DAGs）每种关系类型在周期中独立验证
• 基于标签的索引快速查找并按任意标签过滤
• 双存储模型磁盘上的简单字符串ID，运行时解析指针
• YAML 持久化易于人类阅读且与Git兼容的存储格式
• MCP集成与Claude Desktop、Claude Code以及任何MCP客户端兼容
• 两种交通工具Stdio（用于桌面客户端）和HTTP（用于网络服务）
• 安全突变“克隆-验证-提交”模式可防止无效的图表状态

示例用例

服务器通过简单的YAML配置即可适应任何域名。以下是一个快速示例：

开发任务与工作流程

# mcp.yaml
server:
  name: common-tasks-mcp
  display_name: Common Tasks
naming:
  node:
    singular: task
    plural: tasks

# relationships.yaml
relationships:
  - name: prerequisites
    description: Tasks that must be completed before this task
    direction: backward
  - name: downstream_required
    description: Tasks that must be completed after this task
    direction: forward
  - name: downstream_suggested
    description: Recommended follow-up tasks
    direction: forward

结果像……这样的工具 add_task， list_tasks， get_task 用于管理开发工作流程。

更多示例

以下是完整且可运行的示例，包括：

• 食谱知识库 - 带有食材依赖关系的烹饪食谱
• 微服务依赖跟踪 - 服务网格关系
• 学习路径系统 - 带有先决条件的教育内容
• 基础设施组件 - 基础设施即代码依赖项
• 以及更多。。。

查看 文档/示例/ 包含完整配置文件、示例数据和使用说明的目录。

安装

来自源（或“来源”）

go install ./cli/mcp

使用 Docker

docker compose up -d

Docker 设置将：

• 将数据存储在 ./.tasks 目录（作为卷挂载）
• 在端口8080上以HTTP模式运行
• 启用详细日志记录

配置

域名配置（mcp.yaml)

将此文件放置在您的数据目录中，以配置服务器的身份和术语：

# Server metadata
server:
  # Name of the MCP server (used in protocol identification)
  name: my-graph-mcp

  # Human-friendly display name
  display_name: My Knowledge Graph

  # Instructions shown to clients about how to use this server
  instructions: |-
    This server provides access to [your domain description here].
    Use list_[plural] to browse, get_[singular] to retrieve details,
    and add_[singular] to create new entries.

# Friendly names for graph entities
naming:
  node:
    singular: item        # API uses "add_item", "get_item"
    plural: items         # API uses "list_items"
    display_singular: Item
    display_plural: Items

关系配置（relationships.yaml）

在同一目录中定义你的关系类型：

relationships:
  # Example: Things that come before
  - name: prerequisites
    description: Items that must be completed before this item
    direction: backward

  # Example: Things that come after
  - name: next_steps
    description: Items that should follow this item
    direction: forward

  # Example: Related without temporal ordering
  - name: related_to
    description: Conceptually related items
    direction: none

关系方向：

• backward指向后续出现的节点 之前 按执行/依赖顺序
• forward指向随后出现的节点 之后 按照执行/依赖顺序
• none未暗示时间顺序（概念上的联系）

运行时配置

配置可以通过YAML文件或环境变量来提供：

配置文件（config.yaml）：

transport: stdio
httpPort: 8080
directory: ./data
verbose: false
readOnly: false

环境变量：

• MCP_TRANSPORT传输模式（stdio 或 http）
• MCP_HTTP_PORTHTTP端口号
• MCP_DIRECTORY数据目录路径
• MCP_VERBOSE启用详细日志记录（true/false）
• MCP_READ_ONLY启用只读模式（真/假）

使用方法

启动服务器

标准I/O模式（MCP客户端的默认模式）：

mcp serve --directory ./data

HTTP模式：

mcp serve --transport http --port 8080 --directory ./data

命令行选项

• --directory, -d数据存储的目录（默认：“.”）
• --transport, -t传输模式：stdio 或 http（默认：“stdio”）
• --port, -p使用HTTP传输时的HTTP端口（默认：8080）
• --verbose, -v启用详细日志记录
• --read-only, -r启用只读模式（禁用写入工具）
• --config, -cYAML 配置文件的路径

MCP 工具（自动生成）

服务器根据您的需求动态生成工具 mcp.yaml 配置：

• 列表\_\[复数形式\]列出所有节点或按标签过滤
• 获取\_\[单数\]通过ID获取具有完整关系详情的特定节点
• 列出标签获取所有带有使用次数的唯一标签
• add\_\[单数\]创建一个带有关系的新节点
• 更新\_\[单数\]更新现有节点
• 删除\_\[单数\]删除一个节点并清理所有引用

示例如果你配置 singular: recipe，工具变得 add_recipe， get_recipe， list_recipes等。

MCP 提示（或触发词）

服务器可能包含特定领域的提示（请检查 prompts/ （在您的数据目录中的）目录：

• 生成初始复数形式生成初始图表内容的提示
• 捕获工作流在主动使用期间捕获工作流程的提示

当提示可用时，服务器也会进行注册：

• 提示列表获取所有可用提示及其描述
• 获取提示获取特定提示的完整内容

节点结构

节点以YAML文件的形式存储，结构如下（关系名称根据您的配置而定）：

id: example-node
name: Example Node
summary: Brief description
description: |
  Detailed description explaining this node.
tags:
  - category-a
  - category-b
edges:
  prerequisites:
    - prerequisite-node-1
    - prerequisite-node-2
  next_steps:
    - next-node-1
  related_to:
    - related-node-1
created_at: 2024-01-15T10:30:00Z
updated_at: 2024-01-15T10:30:00Z

注这个（或：那个） edges 键包含所有关系类型。仅持久化ID——指针在运行时解析。

做出贡献

欢迎贡献！这是一个通用框架——如果您构建了一个有趣的领域配置，请考虑将其作为示例分享出来。

看 CONTRIBUTING.md（贡献指南文件） 用于开发设置、架构细节和指南。

许可证

麻省理工学院（MIT）