Electric Elephant

电动大象

Electric Elephant是一个令牌高效的MCP服务器，用于探索和查询 PostgreSQL 来自具有MCP功能的客户端。它是 不 通用SQL桥：只支持PostgreSQL（不支持MySQL、SQLite、SQL Server、Oracle或其他引擎）。

PII和临床数据： 服务器 试图减轻 通过以下方式意外暴露个人身份信息和敏感的临床风格领域 execute_sql （在查询运行之前，对投影进行启发式、失败关闭的检查）。那是一个 尽最大努力保障，不是证书或数据库权限、行级安全性、法律审查或您自己的数据策略的替代品。请参阅目的项目符号和 docs/tools/execute-sql.mdx.

存储库：

上游同步状态

Electric Elephant是dbhub的一个分支。PostgreSQL相关的上游补丁通过dbhub commit同步 72adfdce530ebaf2d7e6df12de5ecde0d174cf4f （2026-04-21），位于上游释放管线的顶部 v0.21.2.

反向上游提交：

• f319114033279532aff2ce9aaef2ce84b127a21f （PostgreSQL getTableComment() 视图支持）
• ce2621d83d78d9ab8b363664c955584cb59ee049 （优雅地跳过及物 MODULE_NOT_FOUND)
• 30d8007998503defc05d5198bcbd9130c609ee41 （HTTP DNS重新绑定保护）
• f13fad459d1ac9f7837fc39e37941247bd6d0c6d （PostgreSQL SSL verify-ca/verify-full + sslrootcert)
• f35144b87f4394dd7a36416b7a459bfd710b61f4 （SSL文档更新 verify-ca / verify-full)
• 72adfdce530ebaf2d7e6df12de5ecde0d174cf4f （源代码描述出现在MCP工具描述中）

目的

• 通过MCP工具公开PostgreSQL(execute_sql, search_objects, query_insights, schema_diff、可观察性助手和相关接线）。
• 仅限PostgreSQL：没有其他SQL数据库的连接器或兼容层。
• 提供安全的默认值（只读，除非明确为破坏性SQL启用）。
• 缓解PII/临床泄漏（尽最大努力）： 启发式防护 execute_sql 除非明确选择，否则会阻止通配符投影和许多看起来敏感的列名（基于名称的启发式方法可能会出现误报或漏报）。选择加入：TOML allow_access_to_pii_data，环境 ALLOW_ACCESS_TO_PII_DATA，或单个DSN CLI 赤裸的 --allow-access-to-pii-data （或 =true / 1 / yes). 破坏性SQL 在单DSN模式下：与相同的模式 --allow-destructive-sql临床命名配置文件包括HL7v2/LIST/LOINC/SNOMED样式标识符。看 docs/tools/execute-sql.mdx, docs/config/command-line.mdx，以及 CLAUDE.md.

存储库地标

• src/index.ts -入口点和启动路径。
• src/server.ts -HTTP MCP传输接线。
• src/connectors/ -数据库连接器实现。
• src/tools/ -MCP工具处理程序(execute_sql, search_objects, query_insights, schema_diff等等）。
• src/config/ -TOML/config加载和验证。
• frontend/ -本地web工作台UI。
• CLAUDE.md -架构和开发惯例。

安装

对于将Electric Elephant作为MCP服务器运行的最终用户：

NPM(npx):

npx electric-elephant --transport http --port 8080 --dsn "postgres://postgres:postgres@localhost:5432/postgres"

Docker：

docker run --rm --init \
  --name electric-elephant \
  --publish 8080:8080 \
  electric-elephant \
  --transport http \
  --port 8080 \
  --dsn "postgres://postgres:postgres@host.docker.internal:5432/postgres"

看 docs/installation.mdx 和 docs/quickstart.mdx 获取完整的客户端设置说明。

开发快速启动

pnpm install
pnpm run dev

构建和测试：

pnpm run build
pnpm test

工作台

Electric Elephant包括一个内置的web工作台，用于运行工具和检查请求跟踪。

• 使用HTTP传输启动服务器（上述示例），然后打开 http://localhost:8080
• 工作台UI： /
• MCP端点： /mcp

更多详情： docs/workbench/overview.mdx

MCP请求流

flowchart LR
    A[MCP Client] --> B[Transport: stdio or HTTP]
    B --> C[Tool Router]
    C --> D{Tool}
    D -->|execute_sql search_objects query_insights schema_diff ...| E[Connector Manager]
    E --> F[PostgreSQL connector]
    F --> G[(PostgreSQL)]
    G --> F --> E --> C --> A

所有内置（包括只读诊断，如 explain_plan, diagnose_locks，以及 replication_status)通过连接器管理器路由到所选源的同一PostgreSQL连接池。

内置MCP工具

默认情况下，这些工具已启用 [[sources]] 除非您将子集列入白名单 [[tools]] 在 dbhub.toml。对于多个源，名称以源id作为后缀（例如 execute_sql_prod_pg).

用户定义的 [[tools]] 条目添加自定义参数化SQL工具。看 docs/tools/overview.mdx 和 dbhub.toml.example.

查询执行状态机

stateDiagram-v2
    [*] --> RequestReceived
    RequestReceived --> ValidatingInput
    ValidatingInput --> SelectingSource
    SelectingSource --> Executing
    Executing --> FormattingResponse
    FormattingResponse --> Completed
    Executing --> Failed
    ValidatingInput --> Failed
    Failed --> [*]
    Completed --> [*]

人类+人工智能代理入职检查表

1. 阅读 CLAUDE.md 在编辑连接器/工具之前。
2. 更喜欢工具级别更改 src/tools/ 传输层变化。
3. 保持 source_id 路由行为向后兼容。
4. 更改时 execute_sql，保留PII保护语义(pii-sql-guard.ts, pii-heuristics.ts, PII_ACCESS_VIOLATION).
5. 运行相关测试(pnpm test，或目标连接器/集成测试）。

工具模式示例

execute_sql 输入（列出显式列； SELECT * 当PII保护处于活动状态时，可能会被拒绝——仅在明确的策略下禁用：TOML， ALLOW_ACCESS_TO_PII_DATA，或裸露 --allow-access-to-pii-data):

{
  "sql": "SELECT id, status FROM users LIMIT 10;"
}

search_objects 输入：

{
  "object_type": "column",
  "schema": "public",
  "table": "users",
  "pattern": "%_id",
  "detail_level": "summary",
  "limit": 50
}

相关文档

• docs/tools/overview.mdx --所有MCP工具和TOML白名单。
• docs/tools/execute-sql.mdx — execute_sql，只读模式，PII保护。
• docs/config/command-line.mdx --CLI标志包括 --allow-access-to-pii-data （单个DSN）。
• docs/tools/search-objects.mdx — search_objects 图案和细节级别。
• docs/tools/query-insights.mdx — query_insights 和 pg_stat_statements.
• docs/tools/schema-diff.mdx — schema_diff 两个来源之间。
• docs/tools/custom-tools.mdx --参数化自定义工具。
• dbhub.toml.example --多源和工具配置示例。
• Mintlify站点配置： docs/docs.json.