koncept-mcp-server

Name: koncept-mcp-server
Author: yourtechtribe-labs

本地服务

github.com/yourtechtribe-labs开发工具212 周前更新

代码仓库

关于 koncept-mcp-server

koncept-mcp-server 为代码库提供经整理的 YAML 语义概念图，适合记录结构代码图难以捕捉的跨文件规则。Agent 可在编辑前查询概念，定义的 invariant 也可作为验证门禁执行检查。

主要功能

01以 YAML 保存整理后的概念
02通过 MCP 工具查询概念
03按文件查找相关概念
04向 Agent 展示建议性 invariant
05静态及命令式 invariant 检查
06用于初始化和验证的 CLI 命令

适用场景

01编辑文件前展示相关代码库规则
02记录缺少结构关联的跨文件 invariant
03在检查到 invariant 违反时使验证失败

MCP 相关

该 MCP 服务提供四种工具，用于查询 YAML 概念注册表，包括查找与特定文件相关的概念。Agent 可在修改代码前通过这些工具获取已记录的 invariant。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "yourtechtribe-labs-koncept": {
      "command": "npx",
      "args": [
        "-y",
        "@yourtechtribe-labs/koncept-mcp-server"
      ]
    }
  }
}

启动命令npx -y @yourtechtribe-labs/koncept-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@yourtechtribe-labs/koncept-mcp-server0.2.0-alpha.7stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
id	string	是

详细介绍

koncepto

面向代码库的语义概念图 MCP 服务——理解代码意味着什么，而不只是它做什么。

简介

代码图（Aider repomap、GitNexus、Sourcegraph）捕捉的是结构关系：谁导入了谁，谁调用了谁。它们会遗漏语义不变量——那些存在于没有导入关系的代码中的跨领域概念：

“修复 B”涉及 7 个文件，但它既不是函数，也不是类
“所有 UI 工作量计数都必须排除手动覆盖的参与者”
“Sector 值字符串必须与 SectorAssignment.sector 键完全匹配”

koncepto 是经过整理的语义层。概念以 YAML 编写，可通过 MCP 工具查询，并在编辑前的第 0 步读取。

状态

预 Alpha（npm 上的 v0.1.0-alpha.3）。在 0.1.0 正式版发布前，架构和工具接口可能会发生变化。请参阅路线图。

本项目使用自身进行试用：仓库中的 5 个概念位于 .koncept/concepts/，涵盖架构、注册表、MCP 工具契约、monorepo 结构和 kebab-id 命名约定。pnpm dogfood = 使用 koncepto verify 验证其自身注册表。

快速入门

# Install in your project
pnpm add -D @yourtechtribe-labs/koncept-cli@alpha

# Bootstrap
npx koncepto init

# Write a concept (YAML)
$EDITOR .koncept/concepts/my-concept.yaml

# Verify
npx koncepto verify

# Register MCP server (Claude Code)
claude mcp add --scope user koncepto -- \
  npx -y @yourtechtribe-labs/koncept-mcp-server@alpha "$PWD"

强制执行的不变量

默认情况下，不变量仅提供建议——通过 koncept_for_file 呈现给 Agent，但不会执行评估。为其提供 check 后，它就会成为强制门禁，koncepto verify 会在检查失败时返回失败：

invariants:
  - id: invalidate-projection-cache
    description: A standalone sync that invalidates the banking cache must also
      invalidate the projection cache, or the /cashflow opening balance goes stale.
    severity: high
    check:
      kind: implication        # per participant file: if it matches `if`, it must also match `then`
      over: { role: writer }
      if: "BankingCacheService"
      then: "CacheInvalidationService|on_full_sync"

静态类型（implication、symbol_present、forbidden、grep）默认会在 koncepto verify 时运行（速度快、只读；使用 --no-checks 可跳过）。Shell 备用机制（kind: command）仅在 koncepto check 时运行。这样，“completion-contract”概念既是检查清单，也是强制门禁——不会因为一时疏忽而跳过待办事项。