Honcho AI

公司治理MCP服务器

一个MCP（模型上下文协议）服务器，为Claude辅助开发提供企业治理。它在运行时向Claude提供治理规则、项目上下文、集成合同、企业技能、依赖性策略、设计系统验证和治理异常验证，并对每次交互进行完整的审计跟踪。

文档

• 设计系统治理架构 --设计系统集成的工作原理：组件注册表、重复检测、令牌验证和可访问性实施。
• 实施准备指南 --在部署治理之前做出的组织和技术决策，以及飞行前检查表。

有关完整的三层治理架构（npm包+CLAUDE.md+MCP服务器），请参阅 企业管治架构.md 在项目根中。

快速开始

npm install
npm run build

# Run with stdio transport (for Claude Code)
npm run start:stdio

# Run with SSE transport (for network deployment)
npm run start:sse

# Development with auto-reload
npm run dev

连接到克劳德代码

添加到您的克劳德代码设置(~/.claude/settings.json):

{
  "mcpServers": {
    "corporate-governance": {
      "command": "node",
      "args": ["/path/to/corporate-governance-mcp-server/dist/index.js"]
    }
  }
}

或者对于网络部署（SSE）：

{
  "mcpServers": {
    "corporate-governance": {
      "type": "sse",
      "url": "http://localhost:3100/sse"
    }
  }
}

工具

服务器公开了十个MCP工具，分为五类。

治理规则

项目背景

企业技能

设计系统

异常处理和审计

目录结构

corporate-governance-mcp-server/
├── src/                          # TypeScript source
│   ├── index.ts                  # Server entry point, tool registration
│   ├── types/index.ts            # All type definitions
│   ├── stores/
│   │   ├── policy-store.ts       # Loads and merges governance policies
│   │   ├── project-registry.ts   # Manages project configs and contracts
│   │   ├── skill-store.ts        # Loads and serves enterprise skills
│   │   ├── component-registry.ts # Loads and queries design system registry
│   │   └── audit-logger.ts       # NDJSON audit trail writer
│   └── tools/                    # One file per MCP tool handler
│
├── policies/                     # Governance rule definitions
│   ├── base/                     # Quality and general rules
│   ├── security/                 # Non-overridable security rules
│   ├── testing/                  # Testing standards and requirements
│   ├── design-system/            # Design system governance rules
│   └── dependency-policy.json    # Package allow/block lists
│
├── projects/                     # Project configuration files
├── contracts/                    # Service integration contracts
│
├── skills/                       # Enterprise skill definitions
│   ├── org/                      # Available to all developers
│   ├── team/                     # Scoped to specific teams
│   │   ├── qa/                   # QA team testing skills
│   │   ├── payments/             # Payments team workflows
│   │   ├── frontend/             # Frontend team patterns
│   │   └── design-system/        # Design system team skills
│   └── project/                  # Scoped to specific projects
│       └── billing-service/
│
├── design-system/                # Design system registry
│   └── component-registry.json   # Generated component/token/standards catalog
│
├── scripts/                      # Build pipeline tools
│   └── generate-registry.ts      # Registry generator for design system CI
│
├── ci/                           # GitHub Actions workflow templates
│   ├── test-governance-gate.yml  # Testing CI gates
│   └── exception-collector.yml   # PR exception reporting
│
└── logs/                         # Audit logs (auto-created)
    └── audit.ndjson

添加策略

策略是带有YAML frontmatter的markdown文件。把它们放进去 policies/{scope}/:

---
id: quality/no-any-types
name: No any Type Usage
scope: quality
severity: error
overridable: true
badExample: |
  const data: any = fetchData();
goodExample: |
  const data: unknown = fetchData();
---

Never use the `any` type in TypeScript. Use `unknown` and narrow, or define proper types.

前线阵地：

策略子目录： base/, security/, quality/, architecture/, testing/, design-system/

现行政策：

添加项目

项目是JSON文件 projects/每个文件都描述了项目的架构、团队、规则和集成点。看 projects/billing-service.json 举一个完整的例子。

关键字段：

项目规则

这 architecture.rules 字段是一个扁平的字符串数组，每个字符串都是Claude在这个项目中工作时必须遵循的架构或领域约束。这些是规定性要求，而不是对代码当前工作方式的描述。只有当团队做出深思熟虑的决定时，他们才会改变。

"rules": [
  "Every API request follows: Route Handler → Input Validation (Zod) → Service → Repository → Database. Route handlers NEVER contain business logic.",
  "All monetary values use the Money value object. Never use raw numbers for currency. All storage is in integer cents.",
  "All Stripe calls go through the stripe-client integration wrapper. Never import Stripe directly in services.",
  "Stripe webhook handlers must be idempotent. Re-processing the same event must not create duplicate charges.",
  "All database writes that affect billing state must be wrapped in transactions."
]

好的规则是稳定的——它们不会引用特定的文件路径（会腐烂）或描述当前的实现（会漂移）。相反，它们规定了Claude应该执行的约束，而不管今天的代码是什么样子。

添加集成合同

合约是JSON文件 contracts/每个文件定义服务的API端点、数据模型、身份验证要求和错误代码。

从OpenAPI规范生成

如果您的服务有OpenAPI规范，请自动生成合约，而不是手动维护：

npx tsx scripts/generate-contract.ts \
  --spec /path/to/user-service/openapi.yaml \
  --output contracts/user-service.json \
  --auth '{"type": "internal-mtls", "details": "Service-to-service calls use mTLS certificates managed by the platform team."}'

生成器从规范中提取端点、请求/响应模式、数据模型和错误代码。通常需要手动输入的唯一字段是 auth.details --关于如何认证的散文解释，通过 --auth 旗帜。

将生成器作为每个服务的CI管道的一部分运行，以便契约与实际的API保持同步。如果服务没有OpenAPI规范，请手动创建JSON合约——请参阅 contracts/user-service.json 对于预期的结构。

添加技能

技能是受管理的、可重用的工作流程，它教会克劳德如何以组织期望的方式执行任务。它们是带有YAML frontmatter的markdown文件，MCP服务器在运行时根据开发人员的团队和项目上下文将它们提供给Claude。

范围目录

技能分为三个范围层次。 所有技能对所有开发人员都是可见的 --范围表示谁拥有和维护技能，而不是谁可以使用它。前端开发人员可以使用QA团队的测试技能，支付开发人员可以参考设计系统贡献工作流。这鼓励了跨团队的知识共享，防止了各自为政。

• skills/org/ — 由平台/治理团队拥有。 组织级技能定义了所有团队应遵循的全公司工作流程。这些为Claude如何在整个代码库中工作奠定了基础。
• skills/team/{team-name}/ — 由特定团队拥有。 团队技能编码了专门的工作流程（例如，QA测试模式、支付集成步骤）。任何开发人员都可以使用它们，但拥有它们的团队有责任保持它们的最新状态。
• skills/project/{project-name}/ — 属于某个特定项目。 项目范围的技能捕获单个代码库独有的工作流。这些是通过以下方式过滤的 project 参数——当开发人员将项目名称传递给 list_skills，他们看到该项目的项目范围技能以及所有组织和团队技能。

创建组织级技能

组织级技能是治理管理员标准化Claude在整个组织中运作方式的主要方式。当你将技能添加到 skills/org/，每个开发人员在致电时都会看到它 list_skills，Claude可以为任何项目加载它。

将文件放入 skills/org/ 并设置 scope: org 在正面：

---
id: org/create-api-endpoint
name: Create API Endpoint
description: "Step-by-step workflow for creating a new API endpoint that follows organizational patterns: route handler, input validation, service method, repository method, and tests."
category: coding-workflow
scope: org
version: "1.2.0"
suggestedTools:
  - get_project_context
  - get_governance_rules
  - check_dependency
tags:
  - api
  - endpoint
  - rest
  - new-feature
---

You are creating a new API endpoint. Follow this workflow exactly. Do not skip steps.

## Step 1: Gather Context
Before writing any code, use `get_project_context` to load the project's architecture...

何时创建组织级技能：

• 工作流程适用于 全部或大部分项目 （例如，创建API端点，审查PR的安全性，加入新的开发人员）
• 你想 防止不一致 跨团队——如果没有组织技能，每个团队的克劳德会议可能会以不同的方式处理同一任务
• 工作流引用 治理工具 (get_governance_rules, check_dependency, validate_exception)这些都是全组织关注的问题
• 你需要一个 可审计、版本化的工作流程 --技能有版本字段，每个技能负载都会记录到审核跟踪中

何时使用团队或项目范围：

• 工作流程特定于一个团队的技术或领域（例如，Stripe集成模式属于 team/payments/)
• 工作流程取决于项目特定的架构，而不是通用的（例如，计费计量管道属于 project/billing-service/)

培养团队技能

团队技能活在 skills/team/{team-name}/ 并且对所有开发人员都是可见的。这 teams frontmatter中的字段表示哪个团队拥有并维护该技能——它不限制访问：

---
id: team/qa/write-api-tests
name: Write Playwright API Tests
description: "QA-governed workflow for Playwright API tests..."
category: coding-workflow
scope: team
teams:
  - qa
  - payments
  - frontend
version: "1.0.0"
suggestedTools:
  - get_project_context
  - get_integration_contract
tags:
  - playwright
  - api
  - testing
---

Full instructions here...

技能前锋参考

技能类别

类别： coding-workflow, review-audit, onboarding, custom

所有权

组织级技能(skills/org/)由平台/治理团队拥有。更改应经过与治理策略更改相同的审查过程——它们会影响每个开发人员的Claude体验。团队和项目技能可以由各自的团队负责人管理。

当前技能：

设计系统集成

治理服务器通过以下方式根据组织的设计系统验证UI组件 check_design_system 工具。这可以防止重复的组件，强制使用令牌，并确保可访问性合规性。

组件注册表

设计系统团队保持 component-registry.json 从设计系统包中作为构建工件生成的文件。它对每个导出的组件、其道具API、变体、关键字、可访问性特征以及全套设计令牌和标准进行了编目。

地点： design-system/component-registry.json

运作原理

重复检测（搜索模式）： 当开发人员要求Claude创建新的UI组件时，Claude会调用 check_design_system 该工具按目的和功能搜索注册表，而不仅仅是名称匹配。对“用户卡”的请求将匹配 ProfileCard 如果它服务于相同的目的。强匹配（60%+相关性）块创建并显示现有组件的完整API。

标准验证（验证模式）： 在构建新组件之前，Claude会根据设计标准验证提案：颜色值是否引用了标记？间距是否使用比例？道具名称是否遵循惯例？是否计划了可访问性属性？描述是否与任何已知的反模式相匹配？

注册表生成器

将生成器脚本作为设计系统CI管道的一部分运行：

npx tsx scripts/generate-registry.ts \
  --source /path/to/design-system/src/components \
  --tokens /path/to/design-system/src/tokens/index.json \
  --standards /path/to/design-system/src/standards.json \
  --output design-system/component-registry.json \
  --package @yourorg/design-system \
  --version 3.2.0

生成器从以下位置读取组件元数据 {ComponentName}.meta.json 每个组件源代码旁边的文件。看 scripts/generate-registry.ts 对于预期的文件结构和自定义点。

CLI选项

--design-registry design-system/component-registry.json   Design system registry path

治理例外

当开发人员需要绕过可重写规则时，异常系统需要一个结构化的理由：

// @governance-exception quality/no-any-types
// Reason: The Stripe webhook SDK returns event.data.object as a 100+ member union...
// Impact: If Stripe changes the payload shape, we get a runtime error instead of compile error...
// Mitigation: validateWebhookPayload() performs runtime validation. Integration test covers all types.
// Expires: 2026-07-01
// Score: 18/20 | APPROVED

这 validate_exception 该工具对每个字段进行评分，并拒绝懒惰的理由（“太难”、“没时间”、“它有效”）。安全规则也不能被排除在外——这些规则要求在治理仓库中有一个问题，以供平台团队审查。

CI扫描每个PR以查找异常注释，在PR上为审阅者发布摘要，标记过期的异常，并使裸构建失败 eslint-disable/@ts-ignore 没有治理例外。

CI工作流

中提供了两个GitHub Actions工作流 ci/:

test-governance-gate.yml --四个并行作业都必须通过：

1. 更改文件的单元测试覆盖率阈值
2. 完整的Playwright套件（API、集成、UI、多浏览器）
3. 测试质量静态分析（断言质量、命名、反模式）
4. 测试存在验证（新的源文件有相应的测试）

exception-collector.yml --扫描PR以查找治理异常，并发布可审查的摘要。在没有治理例外意见的情况下，直接抑制棉绒失败。

将这些复制到每个项目的 .github/workflows/ 目录。

CLI选项

--transport stdio|sse       Transport mode (default: stdio)
--port 3100                 SSE port (default: 3100)
--data-dir .                Base directory for all data directories
--policies-dir policies     Policies directory
--projects-dir projects     Projects directory
--contracts-dir contracts   Contracts directory
--skills-dir skills         Skills directory
--dep-policy policies/dependency-policy.json  Dependency policy file
--audit-log logs/audit.ndjson                 Audit log file path

审计日志

每个工具调用都以NDJSON的形式记录到审计日志文件中。每个事件都包括UUID、时间戳、事件类型、项目上下文和完整的请求详细信息。事件类型： rules_requested, project_context_requested, integration_contract_requested, dependency_checked, skill_listed, skill_requested, security_flag, rule_overridden, code_validated, design_system_checked, component_search.

要将事件传送到外部系统（Datadog、Splunk、CloudWatch），请更换 AuditLogger writer——界面保持不变。