Metadata-Version: 2.4
Name: jh-mes-mcp
Version: 1.0.31
Summary: JH-MES MCP Gateway Bridge - STDIO to HTTP
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: httpx>=0.27.0

# JH-MES MCP Gateway Bridge

JH-MES 智能工厂 MCP 网关的 STDIO 桥接服务。将标准 MCP STDIO 协议转发到 Java HTTP 网关，使 AI 客户端（Cursor / Cherry Studio / 通义灵码 / 魔搭 MCP 广场）能够调用 MES 业务接口。

## 工作原理

```
AI 客户端 (Cursor / Cherry Studio / 魔搭MCP广场)
    │ STDIO (JSON-RPC over stdin/stdout)
    ▼
jh-mes-mcp (Python 桥接包, PyPI: jh-mes-mcp)
    │ HTTP POST (Streamable HTTP / JSON-RPC 2.0)
    ▼
http://mom.azk168.cn/mcp-gateway/mcp (Java MCP 网关, Spring Boot)
    │ RestTemplate
    ▼
jhmes:9090 / jerp:9091 (MES 业务服务)
```

## 提供的工具

| 工具 | 说明 |
|---|---|
| `list_tools` | 列出网关上所有可用的业务接口工具（名称、描述、参数定义） |
| `call_tool` | 调用指定业务接口工具，传入工具名和 JSON 参数 |

**使用流程**：AI 先调 `list_tools` 了解有哪些能力，再调 `call_tool` 执行具体业务操作。

## 快速开始

### 安装

```bash
pip install jh-mes-mcp
```

### 本地运行

```bash
# 默认连接线上网关
jh-mes-mcp

# 指定网关地址
JH_MES_GATEWAY_URL=http://localhost:9093/mcp-gateway/mcp jh-mes-mcp
```

### MCP 客户端配置

**Cursor / VS Code / Cherry Studio**（`mcp.json`）：

```json
{
  "mcpServers": {
    "jh-mes": {
      "command": "uvx",
      "args": ["jh-mes-mcp"],
      "env": {
        "JH_MES_GATEWAY_URL": "http://mom.azk168.cn/mcp-gateway/mcp"
      }
    }
  }
}
```

**Claude Desktop**（`~/.claude/claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "jh-mes": {
      "command": "uvx",
      "args": ["jh-mes-mcp"],
      "env": {
        "JH_MES_GATEWAY_URL": "http://mom.azk168.cn/mcp-gateway/mcp"
      }
    }
  }
}
```

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `JH_MES_GATEWAY_URL` | `http://mom.azk168.cn/mcp-gateway/mcp` | Java MCP 网关地址 |
| `JH_MES_TIMEOUT` | `30` | HTTP 请求超时（秒） |

## 发布到 PyPI

```bash
# 1. 安装构建工具
pip install build twine

# 2. 构建包
cd mcp-bridge
python -m build

# 3. 上传到 PyPI
twine upload dist/*

# 或使用 TestPyPI 测试
twine upload --repository testpypi dist/*
```

## 魔搭 MCP 广场部署

### 方式一：仅分发展示（推荐）

提供 SSE URL 供外部 AI 客户端接入：

```json
{
  "mcpServers": {
    "jh-mes": {
      "type": "sse",
      "url": "http://mom.azk168.cn/mcp-gateway/mcp"
    }
  }
}
```

在 [魔搭 MCP 广场](https://modelscope.cn/mcp) 创建时选择「仅分发展示」，填入上述 URL。

### 方式二：可托管部署

通过 GitHub 仓库由魔搭平台托管运行：

1. 将本项目推到 GitHub
2. 登录 [魔搭 MCP 广场](https://modelscope.cn/mcp) → 创建 MCP
3. 创建类型选择 **「GitHub 快速创建」**
4. 填写：
   - **来源地址**：GitHub 仓库 URL
   - **托管类型**：可托管部署
5. 平台自动读取 `pyproject.toml` 进行构建部署

## 技术栈

| 组件 | 技术 |
|---|---|
| Python 桥接包 | FastMCP (mcp SDK v1/v2 兼容) + httpx |
| Java MCP 网关 | Spring Boot 2.1.2 + MyBatis-Plus |
| 协议 | JSON-RPC 2.0 + Streamable HTTP (MCP 2025-06-18) |
| 打包 | hatchling + PyPI |

## 项目结构

```
mcp-bridge/
├── pyproject.toml              # PyPI 打包配置
├── README.md                   # 本文件
└── src/
    └── jh_mes_mcp/
        ├── __init__.py
        ├── server.py           # 静态版（list_tools + call_tool）
        └── server_dynamic.py   # 动态版（启动时加载所有业务工具为独立 MCP 工具）
```

切换版本：
```bash
# 使用动态版（每个业务工具作为独立 MCP 工具暴露）
copy server_dynamic.py server.py

# 恢复静态版（通用 list_tools + call_tool）
# 用备份覆盖即可
```
