Teukhos (Mihai Ciprian Chezan)

特科斯

______________________________________________________________________

*你描述一下这个工具。Teukhos将其伪造为MCP。*

从单个YAML文件生成生产就绪的MCP服务器。不需要Python编程。

状态：Beta --核心功能稳定且经过测试。API可能在v1.0之前更改。

pip install teukhos
teukhos serve git-tools.yaml

就是这样。你的CLI工具现在可以被任何AI代理调用。

______________________________________________________________________

问题

MCP生态系统存在一个关键差距：

Teukhos填补了这一空白。在YAML中定义你的工具。运行一个命令。完成。

______________________________________________________________________

30秒快速入门

安装：

pip install teukhos
# or: uvx teukhos

创建 teukhos.yaml:

forge:
  name: "my-tools"

tools:
  - name: git_log
    description: "Show recent git commits"
    adapter: cli
    cli:
      command: git
      subcommand: [log, --oneline]
    args:
      - name: count
        type: integer
        flag: "-n"
        default: 10
    output:
      type: stdout

向您的AI客户端注册：

teukhos install teukhos.yaml                           # auto-detect & prompt
teukhos install teukhos.yaml --client cursor            # specific client
teukhos install teukhos.yaml --client claude-code --project  # project-level
teukhos install teukhos.yaml --dest .github/mcp.json   # any JSON file

问克劳德： *“显示最后5次提交”* --它使用该工具。

______________________________________________________________________

运作原理

______________________________________________________________________

CLI参考

teukhos serve [config]            Start the MCP server
teukhos validate [config]         Validate config, exit 0/1 — use in CI
teukhos install [config]          Register with MCP client(s)
teukhos uninstall    Remove from MCP client(s)
teukhos clients                   List supported clients & detection status
teukhos wait-ready                Poll /health until ready — use in CI
teukhos version                   Print version
teukhos discover          Auto-generate config from --help

选项 serve:

--transport  -t    Override transport: stdio | http  (default: from config)
--port       -p    Override HTTP port                (default: 8765)

选项 install:

--client  -c    Target a specific client by slug (e.g., cursor, claude-code)
--all           Install for all detected clients
--project       Use project-level config (e.g., .cursor/mcp.json in cwd)
--url           Remote server URL — enables HTTP mode
--key           API key for HTTP mode (default: "env:TEUKHOS_API_KEY")
--dest          Write to an arbitrary JSON config file (bypasses client detection)
--config-key    JSON key for server entries: "mcpServers" (default) or "servers"

选项 uninstall:

--client  -c    Target a specific client by slug
--all           Remove from all detected clients
--project       Target project-level config

选项 discover:

--output        -o    Output file path (default: .yaml)
--dry-run             Print generated YAML to stdout instead of writing a file
--max-depth     -d    Max recursion depth for subcommands (default: 2)
--timeout       -t    Timeout in seconds for each --help call during discovery [default: 15]
--exec-timeout  -e    Timeout in seconds for tool execution; sets timeout_seconds in generated YAML
--filter        -f    Only discover subcommands under this prefix (e.g. "vm" for "az vm")

配置文件名： Teukhos寻找 teukhos.yaml 默认情况下。遗产 mcp-forge.yaml 会自动接受并附上弃用说明。

______________________________________________________________________

支持的客户

Teukhos可以在这些MCP兼容的AI客户端上注册：

teukhos clients              # see which are detected on your system
teukhos install --all         # register with all detected clients

______________________________________________________________________

serve 对比 install --何时使用Which

teukhos install 是大多数用户的主要命令。它将您的配置注册到AI客户端（Cursor、Claude Code等）。然后客户端生成 teukhos serve 当需要您的工具时，通过stdio自动执行。你不跑 teukhos serve 你自己。

teukhos serve 在两种情况下使用：

1. 测试/调试 --在注册之前，请验证您的YAML配置是否正确启动
2. HTTP服务器模式 --运行远程客户端连接到的持久网络可访问MCP服务器

# Most users: just install, the client handles the rest
teukhos install git-tools.yaml --client cursor

# Testing: verify config works
teukhos serve git-tools.yaml

# HTTP server: run persistently for remote access
teukhos serve git-tools.yaml --transport http --port 8765

______________________________________________________________________

安装到自定义路径(--dest)

使用 --dest 将MCP配置写入任何JSON文件，完全绕过客户端检测。这对 .github/mcp.json自定义设置，或Teukhos尚不了解的客户。

# Write to .github/mcp.json (uses "mcpServers" key by default)
teukhos install git-tools.yaml --dest .github/mcp.json

# Use "servers" key (GitHub Copilot / VS Code format)
teukhos install git-tools.yaml --dest .vscode/mcp.json --config-key servers

# HTTP mode to custom path
teukhos install --dest /path/to/config.json --url http://host:8765/mcp

# Absolute path
teukhos install git-tools.yaml --dest C:\projects\myapp\.cursor\mcp.json

这 --config-key 选项控制用于服务器条目的JSON密钥：

• mcpServers （默认）--用于Claude Desktop、Claude Code、Cursor和大多数客户端
• servers --由GitHub Copilot/VS代码使用

______________________________________________________________________

运行多个服务器

您可以在同一台机器上并行运行多个Teukhos服务器。每个配置都有一个唯一的服务器名称，该名称来源于其 forge.name，因此它们在客户端配置中不会相互覆盖。

stdio（无冲突——每个都是客户端生成的单独子进程）：

teukhos install git-tools.yaml --client cursor       # registers teukhos-git-tools
teukhos install dev-tools.yaml --client cursor        # registers teukhos-dev-tools
# Cursor now has two independent MCP servers, each spawned as its own process

客户端的配置将包含单独的条目：

{
  "mcpServers": {
    "teukhos-git-tools": {
      "command": "teukhos",
      "args": ["serve", "C:/path/to/git-tools.yaml"]
    },
    "teukhos-dev-tools": {
      "command": "teukhos",
      "args": ["serve", "C:/path/to/dev-tools.yaml"]
    }
  }
}

HTTP（使用不同的端口）：

teukhos serve git-tools.yaml --transport http --port 8765 &
teukhos serve dev-tools.yaml --transport http --port 8766 &
teukhos serve media-tools.yaml --transport http --port 8767 &

# Connect clients to each
teukhos install --client cursor --url http://localhost:8765/mcp
teukhos install --client cursor --url http://localhost:8766/mcp

______________________________________________________________________

完整配置参考

forge:
  name: "my-toolset"          # MCP server identity
  version: "1.0.0"
  description: "What this server does"

server:
  transport: stdio             # stdio | http
  host: "127.0.0.1"           # use 0.0.0.0 for remote (add auth!)
  port: 8765
  cors_origins: ["*"]         # CORS origins for HTTP (default: none)

auth:
  mode: none                   # none | api_key
  api_keys:
    - "env:TEUKHOS_API_KEY"    # reads from environment variable (recommended)
    - "env:MY_CUSTOM_KEY"      # any env var name with env: prefix
    - "literal-key-here"       # or use a literal string directly

tools:
  - name: tool_name            # snake_case — used as MCP tool ID
    description: "What the LLM reads to decide when to call this tool"
    adapter: cli               # cli is the only adapter in v0.2

    cli:
      command: "mybinary"      # must be on PATH or absolute path
      subcommand: []           # e.g. ["log", "--oneline"] for git
      timeout_seconds: 30
      working_dir: null        # defaults to cwd
      env: {}                  # extra env vars for this tool

    args:
      - name: arg_name
        type: string           # string | integer | number | boolean
        description: "Shown to the LLM"
        required: false
        flag: "--flag"         # CLI flag: -f or --flag
        positional: false      # true = append at end of command
        default: null
        enum: []               # restrict to allowed values
        secret: false          # redact from logs

    output:
      type: stdout             # stdout | stderr | json_field | exit_code
      field: null              # for json_field: dot-notation path e.g. "data.items"
      exit_codes:              # for exit_code type: map codes to messages
        0: "Success"
        1: "Not found"

______________________________________________________________________

配置示例

Git工具

forge:
  name: "git-tools"

tools:
  - name: git_log
    description: "Show recent git commits"
    adapter: cli
    cli:
      command: git
      subcommand: [log, --oneline]
    args:
      - name: count
        type: integer
        flag: "-n"
        default: 10
    output:
      type: stdout

  - name: git_status
    description: "Show working tree status"
    adapter: cli
    cli:
      command: git
      subcommand: [status, --short]
    output:
      type: stdout

  - name: git_diff
    description: "Show diff of current changes"
    adapter: cli
    cli:
      command: git
      subcommand: [diff]
    args:
      - name: staged
        type: boolean
        description: "Show staged changes only"
        flag: "--staged"
    output:
      type: stdout

系统工具（跨平台）

forge:
  name: "sysops"

tools:
  - name: disk_usage
    description: "Show disk usage for a path"
    adapter: cli
    cli:
      command: python
      subcommand:
        - "-c"
        - "import shutil,sys,os; p=sys.argv[1] if len(sys.argv)>1 else '.'; p=os.path.abspath(p); u=shutil.disk_usage(p); print(f'Total: {u.total/1024/1024:.0f} MB  Used: {u.used/1024/1024:.0f} MB  Free: {u.free/1024/1024:.0f} MB')"
    args:
      - name: path
        type: string
        positional: true
        default: "."
    output:
      type: stdout

  - name: ping_host
    description: "Check if a host is reachable"
    adapter: cli
    cli:
      command: python
      subcommand:
        - "-c"
        - "import subprocess,platform,sys; h=sys.argv[1]; flag='-n' if platform.system()=='Windows' else '-c'; r=subprocess.run(['ping',flag,'3',h],capture_output=True,text=True); print(r.stdout); exit(r.returncode)"
      timeout_seconds: 15
    args:
      - name: host
        type: string
        required: true
        positional: true
    output:
      type: exit_code
      exit_codes:
        0: "Host is reachable"
        1: "Host is unreachable"

JSON输出

  - name: get_video_info
    description: "Get video metadata as JSON"
    adapter: cli
    cli:
      command: ffprobe
      subcommand: ["-v", "quiet", "-print_format", "json", "-show_format"]
    args:
      - name: input_file
        type: string
        required: true
        positional: true
    output:
      type: json_field
      field: "format.duration"   # extract a specific field

______________________________________________________________________

远程服务器/HTTP传输

将Teukhos作为网络可访问的服务器运行：

# remote-server.yaml
server:
  transport: http
  host: "0.0.0.0"
  port: 8765

auth:
  mode: api_key
  api_keys:
    - "env:TEUKHOS_API_KEY"

# Start the server
export TEUKHOS_API_KEY="your-secret-key"
teukhos serve remote-server.yaml

# Connect a client (from any machine)
teukhos install --client cursor --url http://server-ip:8765/mcp

API密钥解析

配置中的键使用 env: 前缀约定：

反向代理后面的部署

对于生产环境，请在nginx或Caddy后面运行以终止TLS：

# nginx example
server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_set_header Host $host;
    }
}

______________________________________________________________________

CI/CD集成

GitHub 操作

- name: Install Teukhos
  run: pip install teukhos

- name: Validate config
  run: teukhos validate teukhos.yaml

- name: Start MCP server
  run: |
    teukhos serve teukhos.yaml --transport http --port 8765 &
    teukhos wait-ready --timeout 30

- name: Run agent tasks
  run: |
    claude --mcp http://localhost:8765/mcp \
      "Analyse the git log and summarise what changed this week"

- name: Teardown
  if: always()
  run: pkill -f "teukhos serve" || true

码头工人

FROM python:3.12-slim
RUN pip install teukhos
COPY teukhos.yaml .
EXPOSE 8765
HEALTHCHECK CMD teukhos wait-ready --timeout 5
CMD ["teukhos", "serve", "--transport", "http"]

手动客户端配置

如果您更喜欢手动设置，请在客户端的MCP配置中添加：

stdio（本地）：

{
  "mcpServers": {
    "teukhos-my-tools": {
      "command": "teukhos",
      "args": ["serve", "/path/to/teukhos.yaml"]
    }
  }
}

HTTP（远程）：

{
  "mcpServers": {
    "teukhos-remote": {
      "url": "http://server:8765/mcp",
      "headers": {
        "Authorization": "Bearer ${TEUKHOS_API_KEY}"
      }
    }
  }
}

或者使用install命令： teukhos install teukhos.yaml --client cursor

______________________________________________________________________

食谱

常见任务的复制粘贴示例。根据您的设置调整路径和名称。

安装并注册

# Install Teukhos
pip install teukhos

# Register git-tools with Cursor (global)
teukhos install git-tools.yaml --client cursor

# Register git-tools with Claude Code (project-level, in current folder)
teukhos install git-tools.yaml --client claude-code --project

# Register with Claude Desktop
teukhos install git-tools.yaml --client claude-desktop

# Register with GitHub Copilot in VS Code (project-level)
teukhos install git-tools.yaml --client github-copilot --project

# Register with Gemini CLI
teukhos install git-tools.yaml --client gemini-cli

# Register with Windsurf
teukhos install git-tools.yaml --client windsurf

# Register with all detected clients at once
teukhos install git-tools.yaml --all

# Auto-detect clients and pick interactively
teukhos install git-tools.yaml

自定义目的地(--dest)

# Write to .github/mcp.json for GitHub Copilot in a repo
teukhos install git-tools.yaml --dest .github/mcp.json --config-key servers

# Write to .vscode/mcp.json with "servers" key
teukhos install git-tools.yaml --dest .vscode/mcp.json --config-key servers

# Write to .cursor/mcp.json in another project
teukhos install git-tools.yaml --dest /home/user/myproject/.cursor/mcp.json

# Write to any path with default "mcpServers" key
teukhos install git-tools.yaml --dest /etc/mcp/shared-tools.json

一台机器上有多台服务器

# Register two different configs with the same client (stdio, no conflicts)
teukhos install git-tools.yaml --client cursor
teukhos install dev-tools.yaml --client cursor

# Run two HTTP servers on different ports
teukhos serve git-tools.yaml --transport http --port 8765 &
teukhos serve dev-tools.yaml --transport http --port 8766 &

# Connect a client to both remote servers
teukhos install --client cursor --url http://localhost:8765/mcp
teukhos install --client cursor --url http://localhost:8766/mcp

远程/HTTP服务器

# Start an HTTP server on localhost (for testing)
teukhos serve git-tools.yaml --transport http

# Start on all interfaces (for network access, requires auth in config)
teukhos serve remote-server.yaml

# Set the API key and start
export TEUKHOS_API_KEY="my-secret-key-abc123"
teukhos serve remote-server.yaml

# Connect a client to a remote server
teukhos install --client claude-code --url http://192.168.1.50:8765/mcp

# Connect with a custom API key
teukhos install --client cursor --url http://myserver:8765/mcp --key "env:MY_SERVER_KEY"

# Connect with a literal key (not recommended for production)
teukhos install --client cursor --url http://myserver:8765/mcp --key "s3cret-t0ken"

# Write remote config to a custom file
teukhos install --dest .vscode/mcp.json --config-key servers --url http://myserver:8765/mcp

验证和测试

# Validate a config (exits 0 if valid, 1 if not — good for CI)
teukhos validate git-tools.yaml

# Test-run a server locally (Ctrl+C to stop)
teukhos serve git-tools.yaml

# Start HTTP server and wait until ready (CI pipelines)
teukhos serve git-tools.yaml --transport http --port 8765 &
teukhos wait-ready --port 8765 --timeout 30

卸载

# Remove from a specific client
teukhos uninstall teukhos-git-tools --client cursor

# Remove from a specific client (project-level config)
teukhos uninstall teukhos-git-tools --client claude-code --project

# Remove from all detected clients
teukhos uninstall teukhos-git-tools --all

从二进制文件中发现工具

# Auto-generate a config (writes .yaml by default, e.g., my-tool.yaml)
teukhos discover my-tool.exe

# Preview without writing a file
teukhos discover my-tool --dry-run

# Scope to a subtree for large CLIs (e.g., Azure CLI)
teukhos discover az.cmd --filter vm

# Limit recursion depth
teukhos discover az.cmd --filter vm --max-depth 1

# Discover, then install in one flow
teukhos discover my-tool -o my-tool.yaml
teukhos install my-tool.yaml --client claude-desktop

列表和发现

# See all supported clients and which are installed on your system
teukhos clients

# Print Teukhos version
teukhos version

# Enable shell tab-completion (PowerShell)
teukhos --show-completion >> $PROFILE

# Enable shell tab-completion (bash)
teukhos --show-completion >> ~/.bashrc

# Enable shell tab-completion (zsh)
teukhos --show-completion >> ~/.zshrc

码头工人

# Build
docker build -t my-mcp-server .

# Run with API key
docker run -e TEUKHOS_API_KEY=my-secret -p 8765:8765 my-mcp-server

# Connect a local client to the container
teukhos install --client cursor --url http://localhost:8765/mcp

______________________________________________________________________

路线图

v0.3——电流

• 多客户端安装程序：支持15个MCP客户端
• 项目级和全球级安装范围
• teukhos install 通过自动检测， --client, --all, --project, --url
• teukhos install --dest 写入任意JSON配置文件
• teukhos install --config-key 选择 mcpServers 或 servers JSON格式
• teukhos uninstall 删除注册
• teukhos clients 列出支持的客户端
• 带有启动横幅的HTTP流式传输
• env: 前缀API密钥解析
• HTTP传输的CORS配置
• 全身份验证中间件（承载令牌）
• 跨平台示例配置（Windows、Linux、macOS）
• 所有示例服务器上的Ping健康检查工具
• 全面的集成测试套件（20台服务器上的62个测试）
• teukhos discover --自动生成配置 --help 随着 --max-depth, --filter，以及 --timeout 选项

v0.4——生产就绪

• rest 适配器（包装任何HTTP端点）
• shell 适配器（内联bash/pwsh脚本）
• 热重载——保存YAML，工具更新无需重启
• 流输出支持
• 锁定文件(teukhos.lock)用于可重复部署

v0.5——平台

• OAuth 2.1+JWT身份验证
• mTLS支持企业部署
• 工具级RBAC
• 仅附加审核日志
• 嵌入式web UI——深色玻璃，实时工具调用可视化
• 双向YAML到可视化编辑器同步
• OpenAPI自动导入适配器
• 工具组成/微型管道
• 普罗米修斯指标 /metrics
• 公共注册表： teukhos install registry://community/git-tools

______________________________________________________________________

为什么选择Teukhos？

您提供MCP规范。Teukhos负责锻造。

______________________________________________________________________

贡献

git clone https://github.com/MihaiCiprianChezan/teukhos
cd teukhos
python -m venv .venv

激活虚拟环境：

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

在开发模式下安装并运行测试：

pip install -e ".[dev]"

# Run all tests (stdio + cross-transport, skips HTTP subprocess tests if no servers running)
pytest tests/ -v

# Run only stdio server tests (fast, no external dependencies)
pytest tests/test_all_servers.py::TestStdioServers -v

# Run only unit tests
pytest tests/ -v -k "not all_servers"

测试套件包括：

• 单元测试 --配置加载、CLI适配器、输出映射、身份验证、安装程序
• MCP协议测试 --通过FastMCP客户端实现完整的JSON-RPC往返
• 集成测试 --所有11个示例配置：ping、工具列表、模式验证、并发

欢迎拉取请求。

______________________________________________________________________

贡献者

______________________________________________________________________

许可证

麻省理工学院——见 许可证.

看 更新日志 版本历史。

*建造于 Mihai Ciprian Chezan*