AdoMcp

AdoMcp

[NuGet] [License: MIT]

一个开箱即用的数据库 Model Context Protocol (MCP) Server，让 AI Agent 能够发现数据库对象、理解表结构和注释、检查索引，并安全地执行 SQL。

A ready-to-run database MCP server for schema discovery, comments, indexes, and controlled SQL execution.

支持 SQL Server、MySQL/MariaDB、PostgreSQL、SQLite 和 Oracle；插件核心遵循 Agent Plugins（Open Plugin Spec）1.0，可用于 Codex、Claude Code、GitHub Copilot App 和 Copilot CLI。

Server name 和 version 由 MCP SDK 根据程序集元数据自动生成；Server 会在 MCP initialize/server/discover 响应中返回根级 instructions，指导客户端先定位连接与对象、只用 query_sql 读数据，并仅在明确授权后调用 execute_sql。

功能

前置要求

• .NET 10 SDK
• 使用插件时，客户端需要允许启动本地 dnx 进程

无需提前安装 AdoMcp。插件和示例配置使用 dnx -y AdoMcp，首次运行时会从 NuGet 获取包。

插件安装

仓库根目录的 plugin.json、mcp.json 和 skills/adomcp/SKILL.md 是通用的 Agent Plugins 1.0 插件核心。.codex-plugin/、.claude-plugin/、.mcp.json 和 marketplace 文件是客户端兼容与分发入口。插件默认以 stdio 启动 AdoMcp，且不会开启写 SQL。

Codex

仓库包含 .codex-plugin/plugin.json，可被 Codex 插件市场或本地插件源使用。若只需要 MCP Server，可直接添加：

codex mcp add adomcp -- dnx -y AdoMcp

Claude Code（cc）

/plugin marketplace add John0King/AdoMCP/plugin install adomcp@adomcp-plugins

安装后执行 /reload-plugins；使用 /mcp 检查 adomcp 是否已连接。

GitHub Copilot CLI

可以从 GitHub 仓库直接安装：

copilot plugin install John0King/AdoMCPcopilot mcp get adomcp

也可以通过 marketplace 安装：

copilot plugin marketplace add John0King/AdoMCPcopilot plugin install adomcp@adomcp-plugins

GitHub Copilot App

在 Copilot App 中打开 Customize → Plugins，添加 John0King/AdoMCP marketplace，然后安装 AdoMcp。本仓库的 .github/plugin/marketplace.json、plugin.json、.mcp.json 和 skill 会作为一个插件加载。

Copilot App/云端 Agent 必须能运行 .NET 10 和访问 NuGet，才能启动这个本地 stdio MCP Server。若运行环境不允许本地进程，请先自行以 HTTP 模式部署 AdoMcp，再按下文配置远程地址。

直接配置 MCP

适用于任何支持本地 MCP 的客户端：

{  "mcpServers": {    "adomcp": {      "command": "dnx",      "args": ["-y", "AdoMcp"]    }  }}

HTTP 模式需先启动服务：

dnx -y AdoMcp -- --http

然后连接端点：

{  "mcpServers": {    "adomcp": {      "url": "http://localhost:5100/mcp"    }  }}

数据库连接配置

AdoMcp 按以下顺序加载配置，后面的来源覆盖前面的来源：

1. 应用目录中的 appsettings.json
2. appsettings.{Environment}.json
3. 用户配置 ~/.adomcp.json（Windows 为 %USERPROFILE%\.adomcp.json）
4. ADOMCP_ 前缀的环境变量
5. .NET User Secrets
6. 命令行 --allow-any-sql（覆盖全局 AllowAnySql，影响动态连接及未单独设置权限的静态连接）

最常用的方式是在用户目录创建 .adomcp.json：

{  "AllowAnySql": false,  "Databases": [    {      "Name": "mydb",      "DbType": "PostgreSql",      "ConnectionString": "Host=localhost;Database=app;Username=postgres;Password=***;",      "AllowAnySql": false,      "Description": "Local development database"    }  ]}

DbType 可选值：SqlServer、MySql、PostgreSql、Sqlite、Oracle。

静态连接显式设置 AllowAnySql 时使用自身的值；省略时继承全局 AllowAnySql。动态连接也继承全局值，不能单独指定。全局值可在配置文件、ADOMCP_ALLOWANYSQL 环境变量或启动参数中设置，命令行优先，默认 false。权限在进程启动时确定；list_connections 的 canWrite 列显示当前生效的权限。

也可以不创建配置文件，让 Agent 在会话中调用 add_connection。动态连接继承启动时确定的全局 AllowAnySql，仅在当前 AdoMcp 进程中有效，重启后不会保留。同名动态连接会覆盖静态连接，直到移除该动态连接。

不要把真实连接字符串提交到 Git。生产环境建议使用环境变量、User Secrets 或客户端的密钥管理能力。

运行模式

默认使用 stdio；stdout 仅传输 MCP JSON-RPC，日志写入 stderr。

# 默认 stdiodnx -y AdoMcp
# 显式 stdio（兼容旧配置）dnx -y AdoMcp -- --stdio
# HTTP，默认监听 http://localhost:5100/mcpdnx -y AdoMcp -- --http
# 安装为全局 .NET tooldotnet tool install -g AdoMcpadomcp

写 SQL 安全开关

execute_sql 按目标连接判断。静态连接可以显式设置 "AllowAnySql": true 开启写入，或省略该项来继承全局设置；动态连接始终继承全局设置。例如：

dnx -y AdoMcp -- --allow-any-sqldnx -y AdoMcp -- --http --allow-any-sql

也可以在配置文件中设置顶层 "AllowAnySql": true，或设置环境变量 ADOMCP_ALLOWANYSQL=true。运行中修改配置文件不会改变当前进程的写入权限。查询和写入使用同一个连接配置，由服务端执行入口检查 SQL 与写入权限。

query_sql 接受单条 SELECT 或 WITH 查询，可带一个末尾分号。检查时跳过字符串、引用标识符和普通注释，拦截写入、DDL、过程调用与事务控制关键字；例如 SELECT 'DELETE' 可以执行，SELECT ... INTO ...、修改数据的 CTE 和多语句批次会被拒绝。MySQL/MariaDB 可执行注释及引用文本中的反斜杠会因语义不明确而被拒绝。此检查是保守的词法过滤，并不解析完整 SQL，也无法识别数据库函数内部的副作用。未引用的名称若命中拦截关键字，也会被拒绝。

内部职责与验证

• ConnectionRegistry：保存启动配置快照、管理动态连接覆盖，并返回包含生效写入策略的配置副本。
• DatabaseService：获取元数据、执行查询或写入；查询调用 SqlQueryGuard，写入检查当前配置的权限。
• DbConnections：创建和打开 ADO.NET 连接，打开失败时释放连接；调用方负责正常路径的释放。
• IDbProvider：保留各数据库的元数据查询实现。
• DatabaseTools：MCP 参数及 CSV/JSON 输出，将异常转成工具错误，取消请求则继续传播。

执行 dotnet test AdoMcp.slnx 验证 SQL 过滤、连接配置覆盖与权限、取消行为及 SQLite 查询/写入/元数据调用。

Agent 推荐工作流

1. 用 list_connections 确认连接。
2. 缺少连接时用 add_connection 添加。
3. 用 list_objects 确认 schema、对象类型和对象名。
4. 用 get_table_schema 查看结构和注释。
5. 涉及键或性能时用 get_table_indexes。
6. 只读验证使用 query_sql。
7. 仅在用户明确授权且 Server 开启写入能力时使用 execute_sql。

Oracle 中未带 owner 的对象可能是 synonym，应先通过 list_objects 解析真实 schema。

环境变量

MCP Registry

AdoMcp 已注册到官方 MCP Registry，Server name 为 io.github.John0King/adomcp。

License

MIT