MCP 数据分析代理

面向本地优先、受治理的 MCP 客户端分析，支持 SQLite 和 PostgreSQL。

mcp-data-analysis-agent 为 MCP 客户端提供了一个小型、可审计的数据访问层，而非直接数据库访问。它在执行前验证 SQL，使用只读连接，限制结果和执行时间，写入基于收据的可观测性记录，并将凭据保留在操作员的机器上。

存在的原因

MCP 客户端可以推理数据，但不应获得不受限制的数据库凭据或静默执行任意语句。本项目为该边界提供了一个本地控制点：

• 将数据库路径、URL、密码和令牌保存在被忽略的 .env 文件中。

• 仅允许单个参数化的 SELECT 或 WITH 语句。

• 阻止变更、DDL、命令、附件、多语句、不安全函数、受限字段和不安全的工件路径。

• 除应用策略外，还要求数据库级别的只读访问。

• 保留规范化 SQL、计时、任务关联、收据、哈希和事件时间线，以供后续审计。

服务器仅使用 stdio。它不托管公共 API、不上传源数据、不存储远程凭据，也不创建生产数据库用户。

Related MCP server: sql-explorer-mcp

功能

• 通过 SQLAlchemy Core 和 SQLGlot 策略验证访问 SQLite 和 PostgreSQL。

• 源、模式、关系、概况、质量/新鲜度和模式漂移发现。

• 验证、解释计划、有界执行、非负偏移分页、取消、超时和并发限制。

• 对公共、内部、机密和受限字段/源的分类。

• 已批准的语义指标、Git 原生配方、周期比较、变更检测和图表推荐。

• 离线 HTML 仪表板、CSV、Parquet、Typst PDF、收据元数据和安全的原子输出目录。

• ClineFlow 上下文加载、任务日志、不可变的查询/运行记录、事件时间线和完整性验证。

• 确定性的零售、SaaS 和支持夹具，包括本地 SQLite 到 PostgreSQL 的奇偶校验夹具。

前提条件

• Python 3.11 或更新版本，以及 uv。

• Typst 用于支持的报表渲染安装。

• PostgreSQL 命令行工具，包括用于本地奇偶校验夹具的 createdb。

• 目标项目中健康的 ClineFlow/OKF 包。

运行 mcp-data-cli preflight 以通过可用的用户范围包管理器安装或报告所需的本地工具。它从不联系配置的源。mcp-data-cli doctor 验证本地安装；未配置的源报告为 configuration_pending，而非安装失败。

安装

将本仓库安装到当前项目中

当代理或操作员被要求将本 GitHub 仓库安装到项目中时，请使用仓库安装程序——而不是裸的 uv tool install 命令：

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

安装程序安装命令行工具并初始化其运行目录。它创建被忽略的确定性零售游乐场，将唯一的私有 MCP_DATA_SOURCE_URL 值写入 .env，写入源策略，并将 MCP 服务器合并到每个检测到的受支持客户端中。它不会将包复制到项目中，也绝不会将数据库 URL 或凭据放入客户端配置中。客户端信任/启用和重启提示仍由每个客户端应用程序控制。

uv tool install 有意安装用户级可执行文件，并且不运行项目变更的后安装钩子。仅当您想单独安装可执行文件时使用它，然后自行运行 mcp-data-cli init。

PyPI 兼容工作流

uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctor

要在包发布之前安装当前仓库版本，请将安装命令替换为：

uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.git

在任何受支持的 MCP 客户端中首次使用服务器时，代理会在 .mcp-data/playground.sqlite 创建并打开一个确定性的仅限开发的零售 SQLite 游乐场。共享的 MCP welcome 工具解释了如何探索它以及如何切换到真实源。init 将相同的游乐场物化到显式项目策略和私有 .env 中，然后经过一次确认后合并安全的 MCP 客户端条目。显式仓库安装程序使用 init --yes，因为运行该安装程序是对这些范围写入的单一授权。

使用 setup --all 仅预览客户端配置，或使用 setup --all --apply 在一次明确确认后仅合并 mcp-data-analysis stdio 条目。它保留不相关的服务器和设置。使用 setup --status 检查检测和当前配置状态。

设置仅配置 MCP 定义。它无法绕过客户端的信任/启用提示或启动/重启 IDE。VS Code 配置细节由 VS Code 和 GitHub Copilot in VS Code 记录；Continue 在其 MCP 指南 中记录了项目 MCP 片段。

校验和验证的发布引导

对于版本化 wheel 及其发布的 SHA-256 校验和：

MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.sh

引导需要 curl 和 uv，使用 sha256sum 或 shasum 验证工件，并且仅在校验和匹配后安装。然后，它像仓库安装程序一样初始化当前项目。它不使用 sudo 或联系生产数据库；它仅创建本地确定性演示数据。

配置一个活动源

标准安装使用恰好一个活动源，名为 data，以及 .env 中恰好一个私有值：MCP_DATA_SOURCE_URL。它不是包常量或测试值——它是操作员更改以指向自己的只读数据库的唯一值。保持 .env 私有；它被 Git 忽略。

首次使用时，data 自动指向生成的零售游乐场。当您准备好将该选择物化到项目 .env 中时，运行 mcp-data-cli init；它写入：

MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'

游乐场是仅限开发的合成数据。它允许新安装立即运行模式发现、受治理的查询、收据和报告；它绝不是生产数据，也不会被后续的 init 运行覆盖。所有受支持的客户端都收到相同的 stdio 服务器欢迎说明和 welcome MCP 工具。

# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30

# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"

[classification.columns]
email = "restricted"

# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

对于 SQLite，将相同的单个变量设为绝对文件路径或 SQLite URL。对于 PostgreSQL，使用 postgres:// 或 postgresql:// URL。无需手动设置方言：

MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

在 CLI 调用中使用 data 作为源参数，例如 mcp-data-cli schema data。代理拒绝不支持的 URL 方案、相对 SQLite 路径以及与 URL 冲突的旧声明方言。已建立的多源策略保持可读，但 init 有意拒绝重写它们；手动迁移或启动新的简化项目。

对于 PostgreSQL，使用专用的最小权限账户，无写入或 DDL 权限。代理还启用只读会话并应用配置的模式搜索路径，但数据库端的访问控制仍然是强制性的。

典型工作流

执行前验证，然后检查计划并运行有界查询：

mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0

当多个操作属于一个分析时，创建显式任务：

mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>

在调用者选择的新目录中生成报告。拒绝现有目录和符号链接遍历。

mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet

每个报告包含离线 HTML、CSV、可选的 Parquet/PDF 工件、收据元数据、路径和内容哈希。生成的工件、源和凭据不得提交。

开发夹具和 PostgreSQL 奇偶校验

init 仅创建上述小型零售游乐场。贡献者可以显式生成额外的确定性合成夹具：

mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
  mcp-data-cli seed-postgres retail --seed 1

dataset-postgres 使用本地 createdb，拒绝现有数据库名称，仅在临时目录中创建 SQLite 数据，然后将其复制到新的 PostgreSQL 数据库中的 mcp_parity 模式。它不需要手动提供的临时 PostgreSQL URL。

seed-postgres 用于已配置的隔离测试数据库。它从环境读取私有测试 URL，并仅替换其保留的 mcp_seed_retail、mcp_seed_saas 或 mcp_seed_support 模式。它从不接触公共/应用模式。

在开发适配器行为时，使用隔离的 PostgreSQL 实例运行完整的本地质量套件。CI 涵盖 linting、类型检查、测试、覆盖率门、真实 Typst 渲染、SQLite/PostgreSQL 奇偶校验、秘密扫描、依赖审计、SBOM 生成和可信发布自动化。

uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okf

安全关键配置、上下文、账本和 SQL 策略模块需要 100% 的行和分支覆盖率。总体门要求至少 90% 的行覆盖率和 85% 的分支覆盖率。

安全与操作契约

• 查询必须参数化，并在数据库连接/执行前进行验证。

• 结果限制和偏移由项目策略治理；调用者 SQL 无法绕过它们。

• 受限列在执行前被拒绝，秘密类参数在可观测性记录中被编辑。

• 任务日志、查询收据、运行和事件存储在 knowledge/ 和 observability/ 下；数据库 URL、原始秘密、源数据库、结果缓存和报告二进制文件被排除。

• 本地合成数据集仅是开发基础设施，而非生产入门。

参见 操作指南、安全策略 和 MIT 许可证 以获取完整的操作和披露契约。

贡献与发布

使用聚焦提交并保留带注释的 checkpoint-* 标签：它们是交付里程碑的显式回滚点。使用重要变更更新活动 ClineFlow 工程日志和知识日志，运行 OKF 验证，然后一起提交实现和知识证据。

GitHub Actions 在发布时构建和验证发行版。发布端点和发布凭据是仓库配置；它们永远不会存储在此代码库中。