使用说明
SankyaMCP
用于Sankhya ERP Oracle数据库的MCP（模型上下文协议）服务器。通过MCP协议将多个命名Oracle连接上的安全SQL执行暴露给AI代理。
概述
- 动态多连接Oracle支持——通过环境变量定义任意数量的命名连接
- 只读工具(
execute_query)仅强制执行SELECT/WITH/EXPLAIN - 可书写工具(
execute_unsafe_query)对于DML/DDL--在只读连接上被阻止 - SELECT查询的CSV输出；DML/DDL成功消息
- Never raises--所有错误返回为
"Erro[...]: ..."字符串 - 内置于 FastMCP 并用 紫外线
先决条件
- Python 3.11+
uv— 安装指南- 无需Oracle客户端（使用
oracledb薄模式） - 可从运行服务器的计算机访问Oracle数据库
设置
- 克隆存储库并安装依赖项：
uv sync
- 在中配置环境变量
.vscode/mcp.json（从该仓库中的模板复制——该文件被git忽略）：
{
"servers": {
"sankhya-mcp": {
"type": "stdio",
"command": "${workspaceFolder}/.venv/Scripts/python.exe",
"args": ["${workspaceFolder}/mcp_server.py"],
"env": {
"ORACLE_CONNECTIONS": "teste,producao",
"ORACLE_TESTE_USER": "your_user",
"ORACLE_TESTE_PASSWORD": "your_password",
"ORACLE_TESTE_DSN": "host:port/service_name",
"ORACLE_PRODUCAO_USER": "your_user",
"ORACLE_PRODUCAO_PASSWORD": "your_password",
"ORACLE_PRODUCAO_DSN": "host:port/service_name",
"ORACLE_PRODUCAO_READONLY": "true",
"ORACLE_DEFAULT_CONNECTION": "teste"
}
}
}
}
- 在VS Code中打开项目——MCP面板将自动检测服务器。
配置连接
连接完全通过环境变量定义，不需要更改代码。
1.声明连接名称
ORACLE_CONNECTIONS=teste,producao,SUP
以逗号分隔的名称列表。如果省略，服务器将恢复为内置默认值(teste 和 producao).
2.为每个连接定义凭据
对于每个名字 {NAME} 如上所述，设置：
| 变量 | 必填 | 描述 |
|---|---|---|
ORACLE_{NAME}_USER |
是 | Oracle用户名 |
ORACLE_{NAME}_PASSWORD |
是 | Oracle密码 |
ORACLE_{NAME}_DSN |
是的 | host:port/service_name |
ORACLE_{NAME}_SCHEMA |
否 | 的架构前缀 ALTER SESSION SET CURRENT_SCHEMA （默认值： {NAME} 上壳） |
ORACLE_{NAME}_DESCRIPTION |
否 | 中显示了人类可读的描述 list_schemas |
ORACLE_{NAME}_READONLY |
否 | 设置 "true" 阻止此连接上的DML/DDL |
3.设置默认连接（可选）
ORACLE_DEFAULT_CONNECTION=SUP
如果省略，则中的第一个连接 ORACLE_CONNECTIONS 使用。
完整示例(mcp.json env块）
"env": {
"ORACLE_CONNECTIONS": "teste,SUP",
"ORACLE_TESTE_USER": "user_teste",
"ORACLE_TESTE_PASSWORD": "pass_teste",
"ORACLE_TESTE_DSN": "host:1521/ORCL",
"ORACLE_TESTE_SCHEMA": "TESTE",
"ORACLE_TESTE_DESCRIPTION": "Base de teste",
"ORACLE_SUP_USER": "user_sup",
"ORACLE_SUP_PASSWORD": "pass_sup",
"ORACLE_SUP_DSN": "host:1521/SUPORTE",
"ORACLE_SUP_SCHEMA": "SUPORTE",
"ORACLE_SUP_DESCRIPTION": "Base de suporte",
"ORACLE_SUP_READONLY": "true",
"ORACLE_DEFAULT_CONNECTION": "teste"
}
可用的MCP工具
list_schemas
列出所有可用的Oracle连接。没有参数。返回CSV。
柱： name, schema, description, readonly, is_default
示例响应：
name,schema,description,readonly,is_default
teste,TESTE,Base de teste,False,True
producao,SANKHYA,Base de produção,True,False
execute_query
执行a 只读 SQL查询（SELECT、CTE、EXPLAIN PLAN）。DML/DDL被拒绝。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
query |
str |
必需的 | SQL语句（SELECT/WITH/EXPLAIN PLAN） |
connection |
str |
null |
连接名称来自 list_schemas，或 null 默认 |
params |
dict |
null |
绑定参数(:name 风格） |
max_rows |
int |
500 |
返回的最大行数 |
offset |
int |
0 |
返回结果前要跳过的行 |
为SELECT查询返回CSV（带标题行）。退货 "Erro[...]: ..." 失败。
execute_unsafe_query
执行任何SQL，包括INSERT、UPDATE、DELETE、DDL和PL/SQL块。连接受阻 readonly=True.
参数与 execute_query。使用前需要明确的用户确认。
退货 "Sucesso: Comando executado (sem retorno)." 对于没有结果集的DML/DDL，或者如果语句返回行，则使用CSV。
查询示例
始终使用连接的架构作为表名的前缀（或依赖于 ALTER SESSION SET CURRENT_SCHEMA):
-- List recent sales orders
SELECT NUNOTA, DTNEG, CODPARC, VLRNOTA
FROM TGFCAB
WHERE DTNEG >= SYSDATE - 30
ORDER BY DTNEG DESC
-- Check a partner with bind param
SELECT CODPARC, NOMEPARC, CGC_CPF
FROM TGFPAR
WHERE CODPARC = :codparc
使用MCP工具：
list_schemas → discover connections
execute_query("SELECT ...", "teste") → read from test DB
execute_query("SELECT ...", "teste", offset=500) → paginate results
execute_unsafe_query("INSERT ...", "teste") → write to test DB
项目结构
mcp_server.py # FastMCP entry point
src/
oracle/
config.py # ConnectionConfig dataclass + env loading
query.py # execute_query() + _is_safe_query() guard
schemas.py # list_schemas_info() + list_schemas_csv()
tools.py # register_tools(mcp) — wires MCP tools
__init__.py # re-exports
tests/
test_oracle.py # pytest unit tests
备注
Referencias/包含开发过程中使用的参考实现。它被git忽略，不属于此项目。- DML/DDL应仅针对可写连接(
readonly=false). - 对于大型结果集，请使用
offset+max_rows分页。