使用说明

神经MCP

Translation layer between Neuro-API and MCP (Model Context Protocol).

A MCP translation layer for Neuro-SDK, allow Neuro to use MCP tools

概述

NeuroMCP弥合了Neuro-AI系统和MCP服务器之间的差距，使Neuro-AI能够使用MCP工具，就像它们是天然的神经动作一样。这座桥作为一个 客户端 它连接到Neuro服务器，并将MCP工具转换为Neuro兼容的动作。

┌─────────────────────────────┐
│   Neuro AI Server           │  ← Neuro test server or real Neuro AI
│   (e.g., test_neuro_server) │
│   Port: 8000                │
└────────────┬────────────────┘
             │
             │ WebSocket (Neuro-API Protocol)
             │
┌────────────▼────────────────┐
│   NeuroMCP Bridge (CLIENT)  │  ← Connects TO Neuro server
│  ┌──────────────────────┐   │
│  │ Neuro Client         │   │  ← Registers actions
│  │ - Connects via WS    │   │
│  │ - Registers actions  │   │
│  │ - Handles execution  │   │
│  └──────────┬───────────┘   │
│             │               │
│  ┌──────────▼───────────┐   │
│  │ Translation Layer    │   │  ← Converts between protocols
│  │ - Schema converter   │   │
│  │ - Result mapper      │   │
│  │ - Name sanitization  │   │
│  └──────────┬───────────┘   │
│             │               │
│  ┌──────────▼───────────┐   │
│  │ MCP Client           │   │  ← Calls MCP tools
│  │ - Stream HTTP        │   │
│  │ - Tool discovery     │   │
│  │ - Tool execution     │   │
│  └──────────────────────┘   │
└─────────────┬───────────────┘
              │
              │ MCP Protocol (Stream HTTP)
              │
┌─────────────▼───────────────┐
│   MCP Server(s)             │
│  - File System              │
│  - Database                 │
│  - Web Search               │
│  - Custom Tools             │
└─────────────────────────────┘

特性

MCP工具→ 神经动作翻译：自动将MCP工具转换为Neuro兼容操作
模式简化：删除Neuro-API不支持的MCP架构功能
流式HTTP传输：支持MCP通信的流HTTP（SSE已弃用）
客户端模式：作为客户端连接到Neuro服务器（无端口冲突）
手动控制：用户驱动的行动注册/注销
实时状态：按需检查连接状态和已注册的操作
代理绕过：自动绕过本地主机连接的系统代理
日志记录与监视：用于调试的全面日志记录

安装

cd NeuroMCP
uv pip install -e .

用法

基本用法

重要提示： 按以下顺序启动服务：

启动Neuro服务器 （测试服务器或真实的Neuro-AI）：

# Option A: Use the included test server
cd NeuroMCP/examples
python test_neuro_server.py

# Option B: Use the Neuro-API console server
cd Neuro-API
python -m neuro_api.server

启动MCP服务器 （例如，用于测试的模拟服务器）：

cd NeuroMCP/examples
python mock_mcp_server.py

运行NeuroMCP桥 （连接到两个服务器）：

cd NeuroMCP
neuromcp --verbose

大桥将：

连接到MCP服务器并发现工具
将MCP工具转换为神经动作
以客户端身份连接到Neuro服务器
在Neuro中注册操作（初始同步）
提供手动控制界面以管理操作
当Neuro请求采取行动时，执行MCP工具

手动控制命令

桥运行后，您可以使用以下命令：

r -将MCP工具注册/同步为神经动作
u -从Neuro中注销所有操作
s -显示连接状态和已注册的操作
q -离开桥

工作流程示例：

启动桥接器（启动时自动注册工具）
如果MCP服务器断开连接，请按 u 取消注册操作
当MCP服务器重新联机时，按 r 重新注册工具
按 s 随时检查连接状态
按 q 彻底关闭这座桥

命令行选项

neuromcp --help

选项：

--mcp-url：MCP服务器MCP端点的URL（默认值： http://127.0.0.1:3000/mcp)
--neuro-url：Neuro服务器的WebSocket URL（默认值： ws://localhost:8000)
--game-name：游戏/应用程序的名称（默认值： NeuroMCP)
--debug：启用调试日志记录
--verbose：启用详细日志记录

程序化使用

import trio
from neuro_mcp import NeuroMCPBridge

async def main():
    bridge = NeuroMCPBridge(
        neuro_websocket_url="ws://localhost:8000",
        game_name="NeuroMCP",
        mcp_server_url="http://localhost:3000/mcp",
    )
    await bridge.run()

trio.run(main)

测试

快速测试（需要3个端子）

终端1：神经测试服务器

cd NeuroMCP/examples
python test_neuro_server.py

预期产量：

[INFO] Starting websocket server on ws://localhost:8000.

终端2：模拟MCP服务器

cd NeuroMCP/examples
python mock_mcp_server.py

预期产量：

============================================================
Mock MCP Server
============================================================

Serving MCP tools via Streamable HTTP at:
  http://localhost:3000/mcp

Available tools:
  - echo: Echo back a message
  - add: Add two numbers
  - greet: Generate a greeting
  - current_time: Get current time

3号航站楼：NeuroMCP桥

cd NeuroMCP
python -m neuro_mcp --verbose

预期产量：

============================================================
NeuroMCP Bridge (Client Mode)
============================================================
MCP Server: http://localhost:3000/mcp
Neuro Server: ws://localhost:8000
Game Name: NeuroMCP
============================================================
...
2025-11-03 12:50:50,202 - neuro_mcp.translation - INFO - Converted MCP tool 'echo' to Neuro action 'echo'
2025-11-03 12:50:50,202 - neuro_mcp.bridge - INFO - Mapped tool: echo -> echo
2025-11-03 12:50:50,202 - neuro_mcp.translation - INFO - Converted MCP tool 'add' to Neuro action 'add'
2025-11-03 12:50:50,202 - neuro_mcp.bridge - INFO - Mapped tool: add -> add
2025-11-03 12:50:50,202 - neuro_mcp.translation - INFO - Converted MCP tool 'greet' to Neuro action 'greet'
2025-11-03 12:50:50,202 - neuro_mcp.bridge - INFO - Mapped tool: greet -> greet
2025-11-03 12:50:50,202 - neuro_mcp.translation - INFO - Converted MCP tool 'current_time' to Neuro action 'current_time'
2025-11-03 12:50:50,202 - neuro_mcp.bridge - INFO - Mapped tool: current_time -> current_time
2025-11-03 12:50:50,202 - neuro_mcp.neuro_client - INFO - Set 4 available actions
2025-11-03 12:50:50,202 - neuro_mcp.bridge - INFO - Synchronized 4 tools as Neuro actions
2025-11-03 12:50:50,202 - neuro_mcp.bridge - INFO - Bridge is running with manual control enabled.

============================================================
MANUAL CONTROL MODE
============================================================
Available commands:
  r - Register/sync MCP tools as Neuro actions
  u - Unregister all actions from Neuro
  s - Show connection status
  q - Quit the bridge
============================================================

Enter command (r/u/s/q):

现在，您可以使用手动控制命令来管理操作注册。

与工具交互

在 端子1 （神经测试服务器），您现在应该看到：

============================================================
CLIENT CONNECTED: ::1:55904
============================================================

Waiting for client to register actions...
(Commands will be available after action registration)


> list

============================================================
Game: NeuroMCP
============================================================
Available actions:
  • echo
    Echo back the provided message
    Schema: {'type': 'object', 'properties': {'message': {'type': 'string'}}, 'required': ['message']}
  • add
    Add two numbers together
    Schema: {'type': 'object', 'properties': {'a': {'type': 'number'}, 'b': {'type': 'number'}}, 'required': ['a', 'b']}
  • greet
    Generate a greeting message
    Schema: {'type': 'object', 'properties': {'name': {'type': 'string'}, 'style': {'type': 'string', 'enum': ['formal', 'casual', 'enthusiastic']}}, 'required': ['name']}
  • current_time
    Get the current time
    Schema: {'type': 'object', 'properties': {}}
============================================================

尝试执行以下工具：

> send greet {"name": "Neuro", "style": "casual"} 

Sending action 'greet'...

============================================================
[CONTEXT from NeuroMCP]
Message: Hey Neuro! What's up?
Reply if not busy: False
============================================================

✓ Action completed successfully
  Result: Hey Neuro! What's up?

使用真正的MCP服务器

要与生产MCP服务器一起使用：

安装并启动MCP服务器（测试：剧作家MCP）

跑桥：

neuromcp --mcp-url http://your-mcp-server:port/mcp

启动测试服务器并发送命令

建筑

组件

MCP客户端 (mcp_client.py)：通过流HTTP传输连接到MCP服务器
转换层 (translation.py)：在MCP和Neuro格式之间转换
神经客户端 (neuro_client.py)：实现Neuro-API客户端协议
桥 (bridge.py)：协调整个翻译过程

客户端模式

这座桥作为一个 神经客户端这意味着：

它 连接到 神经服务器（如测试服务器或真实的神经AI）
它 寄存器 MCP工具作为神经行为
它手柄来自Neuro的动作执行请求

翻译详细信息

工具到行动映射

名称消毒：MCP工具名称转换为 [a-z0-9_-] 格式
模式简化：删除禁止的JSON架构关键字
描述保存：工具描述传递给Neuro

局限性

以下MCP/JSON模式功能是 不支持 （翻译过程中删除）：

架构引用($ref, $defs)
组合关键字(allOf, anyOf, oneOf)
高级验证(additionalProperties, patternProperties)
元关键字($schema, $id, description, title)

故障排除

网桥连接，然后立即断开连接

症状： WebSocket连接在连接后立即关闭

解决：

在启动网桥之前，确保Neuro服务器和MCP服务器正在运行
检查Neuro服务器日志是否有错误

MCP服务器已断开连接

症状： 网桥运行时MCP服务器停止或断开连接

解决：

按 s 检查连接状态
按 u 从Neuro注销所有操作（防止操作调用失败）
重新启动MCP服务器
按 r MCP重新联机后重新注册操作

神经系统中未出现的动作

症状： 启动桥后没有出现动作

解决：

等待几秒钟以完成同步
按 s 验证连接状态
按 r 手动触发注册
在工具转换过程中检查桥接日志是否有错误

发展

项目结构

NeuroMCP/
├── src/neuro_mcp/
│   ├── __init__.py          # Package exports
│   ├── __main__.py          # CLI entry point
│   ├── bridge.py            # Main orchestrator 
│   ├── mcp_client.py        # MCP client 
│   ├── neuro_client.py      # Neuro-API client 
│   └── translation.py       # Translation layer 
├── examples/
│   ├── basic_usage.py       # Example script
│   ├── mock_mcp_server.py   # Test MCP server with 4 tools
│   └── test_neuro_server.py # Test Neuro server
├── pyproject.toml           # Project configuration
└── README.md

许可证

麻省理工学院

鸣谢

原始Neuro SDK：https://github.com/VedalAI/neuro-game-sdk
Neuro SDK的Python实现：https://github.com/CoolCat467/Neuro-API
MCP：https://modelcontextprotocol.io/

使用说明

神经MCP

Translation layer between Neuro-API and MCP (Model Context Protocol).

概述

特性

安装

用法

基本用法

手动控制命令

命令行选项

程序化使用

测试

快速测试（需要3个端子）

终端1：神经测试服务器

终端2：模拟MCP服务器

3号航站楼：NeuroMCP桥

与工具交互

使用真正的MCP服务器

建筑

组件

客户端模式

翻译详细信息

工具到行动映射

局限性

故障排除

网桥连接，然后立即断开连接

MCP服务器已断开连接

神经系统中未出现的动作

发展

项目结构

许可证

鸣谢

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器