overture (Jander99)

序曲

    ](CHANGELOG.md)

多平台MCP和代理编排器 -从单一来源管理所有AI开发工具中的模型上下文协议（MCP）服务器和AI代理。

Overture将MCP配置和AI代理同步到 克劳德代码, GitHub Copilot命令行界面，以及 OpenCode 来自一个统一的配置文件，具有自动客户端检测、版本跟踪、智能合并和同步状态监控功能。

______________________________________________________________________

✨ 特性

MCP服务器管理

• 🎯 单一真相来源 -在一个平台上管理所有MCP服务器 config.yaml 文件
• 🔄 多平台同步 -自动为3+AI客户端生成配置
• 🔍 自动检测 -查找已安装的客户端、版本并验证配置
• 📊 智能合并 -在更新MCP配置时保留用户设置

AI代理管理

• 🤖 通用代理同步 -编写代理一次，同步到所有客户端（Claude Code、OpenCode、Copilot CLI）
• 🔄 代理同步状态 -跟踪哪些代理处于同步状态，哪些代理需要更新
• ✅ 代理验证 -自动YAML模式和Markdown验证
• 🎨 客户端特定格式 -自动转换为每个客户端的代理格式

开发者体验

• 🩺 综合诊断 - doctor 命令显示系统运行状况和同步状态
• 🛡️ 类型安全 -Zod模式验证，并显示有用的错误消息
• 🧪 测试良好 -273个测试，代码覆盖率83%
• 🏗️ 生产准备就绪 -零安全漏洞，TypeScript严格模式

______________________________________________________________________

🚀 快速开始

安装

npm install -g @overture/cli

检查系统运行状况

overture doctor

显示已安装的AI客户端、版本、配置状态和代理同步状态。

输出示例：

Summary:
  Config repo:      exists
  Global agents:    exists (5 agents)
  Project agents:   exists (3 agents)
  Agent sync:       2 in sync, 3 need sync
  Clients detected: 3 / 3
  MCP commands available: 6 / 6

初始化项目

cd your-project
overture init

创建 .overture/config.yaml 具有起动机配置。

同步到所有客户端

overture sync

将MCP和代理同步到所有检测到的客户端。

生成的MCP配置：

• .mcp.json （克劳德代码项目配置）
• ~/.claude.json （Claude Code用户配置）
• .github/mcp.json （GitHub Copilot CLI项目）
• opencode.json （OpenCode项目配置）

已同步代理文件：

• ~/.claude/agents/.md （克劳德密码）
• ~/.config/opencode/agent/.md （OpenCode）
• .github/agents/.agent.md （GitHub Copilot命令行界面）

跳过特定同步类型：

overture sync --skip-agents    # Sync only MCPs
overture sync --skip-skills    # Sync MCPs and agents, skip skills

______________________________________________________________________

📖 文档

• 用户指南 -带示例的完整演练
• 建筑 -技术设计和模式
• 配置架构 -完整的YAML引用
• 例子 -真实世界配置
• 路线图 -即将推出的功能

如何指导

• 添加对新AI客户端的支持
• 设置共享配置存储库
• 测试MCP服务器更改

______________________________________________________________________

💡 配置示例

.overture/config.yaml （项目层面）：

version: '2.0'

# Project metadata
project:
  name: my-python-api
  type: python-backend

# MCP server definitions
mcp:
  # Python REPL for code execution
  python-repl:
    command: uvx
    args: [mcp-server-python-repl]
    transport: stdio

  # Ruff linter integration
  ruff:
    command: uvx
    args: [mcp-server-ruff]
    transport: stdio

  # GitHub integration (exclude from Copilot CLI - it's built-in)
  github:
    command: mcp-server-github
    args: []
    env:
      GITHUB_TOKEN: '${GITHUB_TOKEN}'
    transport: stdio
    clients:
      exclude: [copilot-cli]

# Sync settings
sync:
  backup: true
  backupRetention: 10
  mergeStrategy: append

~/.config/overture/config.yaml （用户全局）：

version: '2.0'

# Global MCP servers (available everywhere)
mcp:
  filesystem:
    command: npx
    args: [-y, '@modelcontextprotocol/server-filesystem', '${HOME}']
    transport: stdio

  memory:
    command: npx
    args: [-y, mcp-server-memory]
    transport: stdio

  brave-search:
    command: npx
    args: [-y, '@modelcontextprotocol/server-brave-search']
    env:
      BRAVE_API_KEY: '${BRAVE_API_KEY}'
    transport: stdio

跑 overture sync 这两个配置会智能地合并！

AI代理配置

~/.config/overture/agents/coding-assistant.yaml:

name: coding-assistant
model: claude-3-5-sonnet
description: Expert coding assistant for Python and TypeScript
tools:
  - filesystem
  - memory
  - github

~/.config/overture/agents/coding-assistant.md:

# Coding Assistant

You are an expert software engineer specializing in Python and TypeScript.

## Guidelines

- Write clean, maintainable code following best practices
- Include comprehensive tests and documentation
- Consider performance and security implications
- Explain your reasoning for architectural decisions

模型映射 (~/.config/overture/models.yaml):

# Map logical names to client-specific model identifiers
claude-3-5-sonnet:
  claude-code: claude-3-5-sonnet-20241022
  opencode: claude-3-5-sonnet-20241022
  copilot-cli: claude-3.5-sonnet

跑 overture sync 通过自动格式转换将代理部署到所有客户端！

______________________________________________________________________

🎯 用例

1.项目专用工具

# Python project gets Python MCP servers
cd python-api && overture sync
# → Syncs python-repl, ruff, pytest

# React project gets JavaScript tooling
cd react-app && overture sync
# → Syncs eslint, prettier, typescript

2.团队标准化

# Share .overture/config.yaml in Git
# Team members sync automatically
overture sync --no-backup

3.多客户端开发

# Use Claude Code for coding
# Use Copilot CLI for terminal
# Use OpenCode for exploration
# → All clients get same MCP servers

4.环境特定配置

mcp:
  database:
    command: psql-mcp
    env:
      DATABASE_URL: '${DATABASE_URL:-postgresql://localhost:5432/dev}'
    platforms:
      exclude: [win32] # Skip on Windows

5.多代理工作流

# Define specialized agents for different tasks
~/.config/overture/agents/
├── code-reviewer.yaml    # Code review and best practices
├── debugger.yaml         # Bug investigation and fixes
├── architect.yaml        # System design and planning
└── tester.yaml          # Test generation and coverage

# Sync all agents to every AI client
overture sync

# Check agent sync status
overture doctor --verbose
# → Shows which agents are in sync across clients

______________________________________________________________________

🛠️ 核心命令

同步选项：

overture sync --skip-agents      # Skip agent synchronization
overture sync --skip-skills      # Skip skill synchronization
overture sync --skip-plugins     # Skip plugin installation
overture sync --dry-run          # Preview without making changes
overture sync --detail           # Show detailed output with diffs

跑 overture --help 以获取完整的命令参考。

______________________________________________________________________

🏗️ 建筑

序曲使用 六边形建筑 通过依赖注入：

apps/cli/              # CLI application
├── src/
│   ├── commands/      # CLI command handlers
│   ├── core/          # Business logic
│   └── main.ts        # Entry point

libs/
├── domain/               # Core types and schemas
│   ├── config-types/     # TypeScript interfaces
│   ├── config-schema/    # Zod validation schemas
│   ├── diagnostics-types/# Diagnostic result types
│   └── errors/           # Error hierarchy
├── ports/                # Interface definitions
│   ├── filesystem/       # File operations
│   ├── process/          # Process execution
│   └── output/           # Logging and output
├── adapters/             # Infrastructure implementations
│   ├── client-adapters/  # AI client adapters
│   └── infrastructure/   # Node.js adapters
├── core/                 # Domain logic
│   ├── config/           # Config loading/merging
│   ├── sync/             # Multi-client sync engine
│   ├── discovery/        # Client detection
│   ├── diagnostics/      # System health checks
│   ├── agent/            # Agent sync and transformation
│   ├── plugin/           # Plugin management
│   └── skill/            # Agent Skills sync
└── shared/               # Shared utilities
    ├── formatters/       # Diagnostic output formatting
    └── utils/            # Common utilities

技术栈：

• 语言： TypeScript 5.9（严格模式）
• 构建系统： Nx 22单回购
• CLI框架： 指挥官.js
• 验证： 黄道带
• 测试： Vitest（273次测试，83%覆盖率）
• Bundler： esb构建

______________________________________________________________________

🧪 发展

先决条件

• Node.js 20+
• npm 10+
• Nx CLI（可选，或使用 npx nx)

设置

# Clone repository
git clone https://github.com/overture-stack/overture.git
cd overture

# Install dependencies
npm install

# Run tests
nx test @overture/cli

# Run tests with coverage
nx test @overture/cli --coverage

# Build CLI
nx build @overture/cli

# Run locally
node dist/apps/cli/main.js --help

测试

# Run all tests
nx test @overture/cli

# Watch mode
nx test @overture/cli --watch

# Specific test file
nx test @overture/cli --testFile=sync.spec.ts

# E2E tests
nx e2e @overture/cli-e2e

掉毛

# Lint all projects
nx run-many -t lint --all

# Fix auto-fixable issues
nx run-many -t lint --all --fix

编码结构

• 测试与源文件位于同一位置(*.spec.ts)
• 每个文件一个类/主函数
• 使用依赖注入（基于构造函数）
• 遵循Nx模块边界（由ESLint强制执行）

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南：

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feat/amazing-feature)
3. 写 测试您的更改
4. 提交 常规承诺(feat:, fix:, docs:等等）
5. 推 到你的叉子
6. 打开 拉取请求

常规承诺

feat: add support for Windsurf client
fix: resolve path resolution on Windows
docs: update installation instructions
test: add tests for config merging
refactor: simplify sync engine logic

代码质量标准

• ✅ TypeScript严格模式（否 any 类型）
• ✅ 所有测试均已通过(nx test @overture/cli)
• ✅ 没有ESLint错误(nx run-many -t lint --all)
• ✅ 代码覆盖率保持不变（>65%）
• ✅ 文件已更新

______________________________________________________________________

🐛 故障排除

常见问题

“找不到配置文件”

# Initialize config first
overture init

“未检测到客户端”

# Check system status
overture doctor

# Force sync without detection
overture sync --skip-binary-detection

“未设置环境变量”

# Use defaults in config
env:
  GITHUB_TOKEN: '${GITHUB_TOKEN:-your-default-token}'

“权限被拒绝”错误

# Check file permissions
ls -la ~/.config/overture/
chmod 644 ~/.config/overture/config.yaml

“代理未同步”

# Check agent sync status
overture doctor --verbose

# Verify agent files exist
ls -la ~/.config/overture/agents/

# Force sync agents only
overture sync --skip-skills

# Validate agent YAML syntax
overture validate

“找不到代理模型”

# Add model mapping to ~/.config/overture/models.yaml
claude-3-5-sonnet:
  claude-code: claude-3-5-sonnet-20241022
  opencode: claude-3-5-sonnet-20241022
  copilot-cli: claude-3.5-sonnet

调试模式

启用详细日志记录：

DEBUG=1 overture sync

显示：

• 堆栈错误跟踪
• 详细的验证消息
• 文件操作日志

看 故障排除指南 更多解决方案。

______________________________________________________________________

📊 项目状态

当前版本： v0.4.0（生产就绪）

测试覆盖范围：

• 273项测试通过
• 83%的代码覆盖率
• 全面的代理同步和诊断测试

安全：

• ✅ 零已知漏洞
• ✅ 定期更新依赖关系
• ✅ TypeScript严格模式

路线图亮点：

• 多仓库技能分享
• MCP市场整合
• VS代码扩展
• 用于配置的Web UI

看 更改日志.md 版本历史。

______________________________________________________________________

📜 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• Claude代码团队 -对于令人惊叹的AI开发平台
• 模型上下文协议 -用于标准化AI工具集成
• Nx团队 -对于优秀的monorepo工具
• 社区贡献者 -用于反馈和错误报告

______________________________________________________________________

🔗 相关项目

• Claude代码工作流 -插件市场
• Claude代码流 -多代理执行
• MCP服务器 -官方MCP服务器实施

看 docs/related-projects.md 以进行详细比较。

______________________________________________________________________

💬 支持

• 文档： docs/user-guide.md
• 问题：
• 讨论：

______________________________________________________________________

Made with ❤️ by the Overture Team