MyGoNavi/cmd/gonavi-mcp-server

GoNavi MCP Server

gonavi-mcp-server 会把 GoNavi 已保存连接背后的数据库能力通过 MCP 暴露给外部客户端。本机客户端默认使用 stdio；云端 Agent 可使用显式开启的 Streamable HTTP 模式。

当前提供的 tools

• get_connections
  • 返回 GoNavi 已保存连接的 id/name/type/target/defaultDatabase 等摘要信息
• get_databases
  • 入参：connectionId
• get_tables
  • 入参：connectionId、可选 dbName
• get_columns
  • 入参：connectionId、可选 dbName、tableName
• get_table_ddl
  • 入参：connectionId、可选 dbName、tableName
• execute_sql
  • 入参：connectionId、可选 dbName、sql
  • 默认只允许只读 SQL
  • 如果 SQL 包含 DDL/DML，必须显式传 allowMutating=true
  • maxRowsPerResult 用来限制单个结果集返回的行数，默认 200

远程 Agent 只需要库表结构时，启动 HTTP 模式请加 --schema-only。该模式不注册 execute_sql，只保留连接摘要、库表、字段、索引、外键、触发器和 DDL 工具。

运行方式

开发态直接运行：

go run ./cmd/gonavi-mcp-server

显式运行本机 stdio：

go run ./cmd/gonavi-mcp-server stdio

也可以先编译：

go build -o .\bin\gonavi-mcp-server.exe .\cmd\gonavi-mcp-server

远程 Agent 使用 Streamable HTTP 时必须设置 bearer token：

$env:GONAVI_MCP_HTTP_TOKEN = "<随机token>"
go run ./cmd/gonavi-mcp-server http --addr 127.0.0.1:8765 --path /mcp --schema-only

安装包主程序也支持同样模式：

& "C:\Program Files\GoNavi\GoNavi.exe" mcp-server http --addr 127.0.0.1:8765 --path /mcp --token "<随机token>" --schema-only

默认建议只监听 127.0.0.1，再通过 SSH 隧道、反向代理或内网网关暴露给云端 Agent。不要在没有 TLS、防火墙和鉴权的情况下直接监听公网地址。

无图形界面或需要把配置交给云端 Agent 时，可直接生成 OpenClaw / Hermans 等远程 MCP 配置：

& "C:\Program Files\GoNavi\GoNavi.exe" mcp-server remote-config --client openclaw --url "https://<你的域名或隧道地址>/mcp" --token "<随机token>" --schema-only

独立 server 开发态也支持同样能力：

go run ./cmd/gonavi-mcp-server remote-config --client hermans --url "https://<你的域名或隧道地址>/mcp" --token "<随机token>" --schema-only

Claude Code / Codex / OpenClaw / Hermans

正式安装包场景，推荐直接在 GoNavi 里使用“AI 设置 -> MCP 服务 -> 安装到 Claude Code / 安装到 Codex”。

它会自动把当前安装的 GoNavi.exe 写入 Claude Code 的用户级 ~/.claude.json，命令形态类似：

{
  "mcpServers": {
    "gonavi": {
      "type": "stdio",
      "command": "C:\\Program Files\\GoNavi\\GoNavi.exe",
      "args": ["mcp-server"],
      "env": {}
    }
  }
}

这样用户不需要自己找本机 gonavi-mcp-server.exe 路径，安装包本体就能直接作为 MCP 入口。

Codex 当前使用 ~/.codex/config.toml，GoNavi 会写入类似下面这段：

[mcp_servers.gonavi]
command = 'C:\Program Files\GoNavi\GoNavi.exe'
args = ['mcp-server']
startup_timeout_sec = 60

仓库开发态如果要在本机 Claude Code CLI 里稳定使用这个 MCP，仍然推荐走仓库内包装脚本：

.\tools\claude-gonavi-mcp.ps1 -p "必须调用 gonavi MCP 的 get_connections 工具"

或者：

tools\claude-gonavi-mcp.cmd -p "必须调用 gonavi MCP 的 get_connections 工具"

这个脚本会先构建 bin\gonavi-mcp-server.exe，再通过 --mcp-config 和 --strict-mcp-config 把 GoNavi MCP 单独注入当前 Claude 会话，避免默认混合 MCP 加载时序导致的首轮工具未挂载问题。

OpenClaw、Hermans 这类部署在云端或远端 Linux 的 Agent，不能直接使用 Windows 本机的 stdio 命令。GoNavi 的连接信息和数据库密码仍应留在 Windows 本机，由 GoNavi MCP 读取保存连接和系统凭据；远端 Agent 只拿到 MCP tools 和 connectionId。

推荐接入形态：

1. Windows 本机运行 GoNavi，并保持能访问已保存的数据库连接。
2. 在 Windows 本机启动 GoNavi.exe mcp-server http --addr 127.0.0.1:8765 --path /mcp --token <随机token> --schema-only。
3. 通过 SSH 隧道、反向代理或内网网关把 http://127.0.0.1:8765/mcp 暴露为云端 Agent 可访问的 HTTPS 地址。
4. 在 OpenClaw / Hermans 中添加远程 MCP Server，transport 选择 Streamable HTTP，URL 指向 /mcp 地址，并设置请求头 Authorization: Bearer <随机token>。
5. 先调用 get_connections 获取 connectionId，再调用 get_databases、get_tables、get_columns、get_table_ddl 等工具读取结构。

如果目标 Agent 支持 mcpServers JSON，可按下面的通用片段配置：

{
  "mcpServers": {
    "gonavi": {
      "type": "streamable-http",
      "url": "https://<你的域名或隧道地址>/mcp",
      "headers": {
        "Authorization": "Bearer <随机token>"
      }
    }
  }
}

不要把数据库 host/user/password 写入云端 Agent 的配置文件。默认 --schema-only 不暴露 execute_sql；如果你明确需要远程执行 SQL，可以去掉该参数，此时 execute_sql 仍受 GoNavi AI 安全设置控制，写操作必须显式传 allowMutating=true。

MCP 客户端配置示例

开发态：

{
  "mcpServers": {
    "gonavi": {
      "command": "go",
      "args": ["run", "./cmd/gonavi-mcp-server"]
    }
  }
}

Windows 独立 server 编译产物（开发态）：

{
  "mcpServers": {
    "gonavi": {
      "command": "D:\\Work\\CodeRepos\\GoNavi\\bin\\gonavi-mcp-server.exe",
      "args": []
    }
  }
}

Windows 已安装 GoNavi（推荐给最终用户）：

{
  "mcpServers": {
    "gonavi": {
      "type": "stdio",
      "command": "C:\\Program Files\\GoNavi\\GoNavi.exe",
      "args": ["mcp-server"],
      "env": {}
    }
  }
}

使用说明

• 先调用 get_connections，拿到 connectionId
• 之后所有数据库工具都只传 connectionId，由 GoNavi 服务端内部解析保存连接和密钥
• 如果 dbName 为空，会优先使用该保存连接里的默认数据库
• Server 会读取 GoNavi 当前活动数据目录里的连接配置，并通过系统 keyring/凭据管理器解析密文
• 如果本机凭据存储不可用，依赖密钥的连接会返回对应错误