opc-mcp 0.1.1

MCP server for order center database access

OPC-MCP

订单中心数据库 MCP 服务，通过 MCP 协议暴露数据库查询能力，供 AI 助手动态查询和排查订单问题。

功能

• 配置驱动工具 — 在 config.yaml 中定义 SQL 模板，自动生成 MCP 工具
• run_query — 动态执行任意 SELECT 查询，支持命名参数、LIKE 自动检测、分页
• query_table_desc — 查询表结构信息（列名、数据类型、注释），表名大小写不敏感
• 多连接池 — 支持多个数据库（opc、smc 等），连接池名称大小写不敏感
• 安全防护 — 仅允许 SELECT 语句，拒绝多语句注入，参数化查询

安装

pip install -e .

配置

编辑 config.yaml：

server:
  host: "0.0.0.0"
  port: 8000

pools:
  opc:
    host: 10.0.0.1
    port: 1521
    user: readonly
    password: xxx
    database: opc_db
    pool_size: 5
  smc:
    host: 10.0.0.2
    port: 1521
    user: readonly
    password: xxx
    database: smc_db
    pool_size: 3

tools:
  query_sub_order:
    description: "查询子订单信息"
    pool: opc
    sql: "SELECT * FROM or_sub_order WHERE 1=1 AND order_id = :order_id AND status = :status"
    params:
      order_id:
        type: str
        description: "订单号"
      status:
        type: str
        description: "订单状态"
    limit:
      default: 50
      max: 100
    offset:
      default: 0

启动

# Streamable HTTP 模式（默认）
uv run opc-mcp --config config.yaml

# SSE 模式
uv run opc-mcp --config config.yaml --mode sse

# stdio 模式（本地进程通信）
uv run opc-mcp --config config.yaml --mode stdio

# 指定日志级别
uv run opc-mcp --config config.yaml --log-level DEBUG

连接地址

模式	连接方式
Streamable HTTP（默认）	http://localhost:8000/mcp
SSE	http://localhost:8000/sse
stdio	通过 stdin/stdout 通信

MCP 客户端配置

Streamable HTTP 模式：

{
  "mcpServers": {
    "opc-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE 模式：

{
  "mcpServers": {
    "opc-mcp": {
      "url": "http://localhost:8000/sse"
    }
  }
}

stdio 模式（通过 cwd 指定项目目录）：

• uv启动方式

{
  "mcpServers": {
    "opc-mcp-stdio": {
      "command": "uv",
      "args": [
        "run",
        "opc-mcp",
        "--config",
        "config.yaml",
        "--mode",
        "stdio"
      ],
      "cwd": "D:/code/python/opc-mcp"
    }
  }
}

• uvx启动方式

{
	"mcpServers": {
	  "opc-mcp-stdio": {
		"command": "uvx",
		"args": [
		  "--from", "D:/code/python/opc-mcp",
		  "opc-mcp",
		  "--config", "D:/code/python/opc-mcp/config.yaml",
		  "--mode", "stdio"
		]
	  }
	}
}

MCP 工具

run_query

动态执行 SELECT 查询，支持命名参数和分页。

参数：

参数	类型	必填	说明
sql	string	是	SELECT SQL，使用 :param_name 占位符
params	object	否	命名参数，key 大小写不敏感
pool	string	否	连接池名称，默认 opc
limit	integer	否	返回行数限制，默认 50，最大 200
offset	integer	否	分页偏移量，默认 0

示例：

{
  "sql": "SELECT * FROM or_dict_def WHERE dict_type = :dict_type AND dict_class = :dict_class",
  "params": {"dict_type": 18, "dict_class": 1},
  "pool": "opc"
}

支持 JOIN、GROUP BY、子查询、UNION、聚合等复杂查询。LIKE 条件自动检测并包裹 %。

query_table_desc

查询表的列结构信息。

参数：

参数	类型	必填	说明
table_name	string	是	表名，大小写不敏感
pool	string	是	连接池名称

示例：

{
  "table_name": "or_dict_def",
  "pool": "opc"
}

返回：

{
  "table_name": "OR_DICT_DEF",
  "count": 5,
  "columns": [
    {"table_name": "OR_DICT_DEF", "column_name": "DICT_TYPE", "data_type": "NUMBER", "comments": "字典类型"},
    {"table_name": "OR_DICT_DEF", "column_name": "DICT_NAME", "data_type": "VARCHAR2", "comments": "字典名称"}
  ]
}

测试

pytest tests/ -v

项目结构

src/opc_mcp/
  main.py           # 入口，服务创建与启动
  config.py          # 配置模型（AppConfig, ToolConfig, PoolConfig）
  pool_manager.py    # 连接池管理
  handlers.py        # 工具执行逻辑
  register.py        # MCP 工具注册
  tools.py           # SQL 校验、参数绑定等工具函数