bach MCP

巴赫mcp

bach-mcp 桥梁 bach.roll 在Max中，AI有两种模式：

1. 克劳德模式：克劳德桌面\MCP(py/main.py)\最大
2. 本地模式：Ollama+Qwen(py/main_local.py)\最大

依赖关系说明

使用 requirements.txt （生成自 requirements.in).

• 请使用： requirements.txt
• 源文件： requirements.in
• 请勿使用： pip_requirements.txt （它不是此回购的一部分）

文件映射（每个文件的用途）

根文件

• README.md：设置和使用。
• environment.yml：Conda-env定义（Python 3.11）。
• requirements.in：直接依赖Python(mcp, requests).
• requirements.txt：pip安装的固定、编译的依赖锁。
• claude_desktop_config.json：示例Claude Desktop MCP服务器配置（编辑绝对路径）。
• .gitignore：不包括缓存/构建/本地工件（包括 .DS_Store 和 __pycache__).
• .gitattributes：Git文本规范化。

Python入口点

• py/main.py：开始 BachMCPServer，创建FastMCP应用程序，在Claude Desktop的stdio上运行MCP。
• py/main_local.py：使用Ollama/Qwen的本地终端REPL模式。

Python包(py/bach_mcp)

• py/bach_mcp/__init__.py：公共出口。
• py/bach_mcp/server.py：高级网桥服务器（消息队列、发送/等待帮助程序、生命周期）。
• py/bach_mcp/tcp.py：低级TCP服务器/客户端类(3001 入境， 3000 出境）。
• py/bach_mcp/mcp_app.py：Claude面临FastMCP工具注册（46个工具）。
• py/bach_mcp/ollama_bridge.py：Ollama聊天客户端+工具调用循环+工具执行器。
• py/bach_mcp/ollama_utils.py：Ollama启动、模型发现、模型选择/拉取菜单。
• py/bach_mcp/tool_registry.py：Qwen的本地工具模式(core 和 extended 集）。

最大包文件数

• max/bach-mcp/patchers/bach-mcp.maxpat：修补程序包含 bach.roll, bach.portal，以及 node.script.
• max/bach-mcp/js/bachTCP.js：Max TCP网桥的节点。

- Max继续收听 0.0.0.0:3000 用于Python命令。 - Max客户端连接到Python 127.0.0.1:3001 用于回复/事件。

生成/非源工件

• .DS_Store, __pycache__/, *.pyc：生成的文件，不是运行时逻辑的一部分。

设置（两种模式共享）

1. 克隆：

git clone https://github.com/agustinissidoro/bach-mcp.git
cd bach-mcp

1. 创建/激活环境：

conda env create -f environment.yml
conda activate bach-mcp

1. 从以下位置安装Python依赖项 requirements.txt:

python -m pip install -r requirements.txt

1. 安装Max软件包：

复制 max/bach-mcp 进入Max包。

• macOS默认值： ~/Documents/Max 9/Packages/
• Windows默认值： %USERPROFILE%\Documents\Max 9\Packages\

1. 在Max中，打开 max/bach-mcp/patchers/bach-mcp.maxpat 并启动Node脚本(script start).

模式1：克劳德模式（MCP）

1. 安装克劳德桌面： https://claude.ai/download
2. 将Claude Desktop指向此MCP服务器。

Claude配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

例子：

{
  "mcpServers": {
    "bach-mcp": {
      "command": "/absolute/path/to/python",
      "args": ["/absolute/path/to/bach-mcp/py/main.py"],
      "cwd": "/absolute/path/to/bach-mcp"
    }
  }
}

然后完全重新启动Claude Desktop。

模式2：本地模式（Ollama+Qwen）

1. 安装Ollama： https://ollama.com
2. 启动本地模式：

python py/main_local.py

发生了什么：

• 确保Ollama正在运行（启动 ollama serve 如果需要）。
• 显示交互式模型选择器（已安装的模型）。
• 如果不存在模型，则提供从已知Qwen标签的拉取/下载。
• 启动终端聊天循环，并通过同一TCP网桥将工具调用路由到Max。
• 使用 core 默认情况下，此入口点中的工具层(BridgeConfig.extended_tools=False).

适用于较大的本地型号（32B/72B）：

python py/bach_mcp/ollama_bridge.py

REPL自动启用 extended 32B/72B标签的工具。

Ollama+Qwen实施细节

本地模式使用以下组件：

1. 模型生命周期(py/bach_mcp/ollama_utils.py)

• QWEN_MODELS 定义已知的Qwen标签和偏好顺序。
• ensure_ollama_running() 检查 /api/tags 并在需要时启动Ollama。
• select_model() 显示已安装的型号，并支持拉取新型号。

1. 网桥配置(py/bach_mcp/ollama_bridge.py)

• BridgeConfig 定义模型、回退模型、温度、令牌限制、TCP端口和工具层。
• 默认传输与克劳德模式相同：传出 3000，传入 3001.

1. 工具调用循环(py/bach_mcp/ollama_bridge.py)

• OllamaClient.chat() 打电话给Ollama /api/chat 随着 tools.
• OllamaBridge._run_tool_loop() 执行迭代工具循环（最多 max_tool_rounds).
• 在缺少模型时，它可以从配置列表切换到已安装的回退模型。

1. 工具执行(py/bach_mcp/ollama_bridge.py + py/bach_mcp/tool_registry.py)

• tool_registry.py 定义了两个本地工具集：

- 核心：12个工具（默认，适用于较小型号） - 扩展：共46个工具（核心+高级）

• ToolExecutor 通过将工具名称映射到Max命令 BachMCPServer.

1. 共享最大传输(py/bach_mcp/server.py + py/bach_mcp/tcp.py)

• 两种模式的运输栈相同。
• 命令转到端口上的Max 3000；响应/事件再次出现 3001.

可选：重新生成 requirements.txt

如果你改变 requirements.in，使用pip工具重建锁文件：

pip-compile --output-file=requirements.txt requirements.in