Mcpkit Data

🚀 麦普金数据

为希望停止上下文切换并开始发货的数据工程师提供的终极MCP服务器 ✨

全面 模型上下文协议 服务器，赋予您的AI助手处理Kafka、数据库、AWS、数据管道等的超能力。停止在终端、仪表板和文档之间跳转。让你的AI来做。

 

______________________________________________________________________

⚠️ 早期免责声明

嘿！ 👋 在你深入了解之前，先来了解一下：

这是一个 全新项目 刚出炉🍞. 我们正在讨论：

• 🆕 首次发布 -就像，刚出生
• 🧪 可生产的 -更像是“在我的机器上工作”准备就绪
• 👥 有限的测试 -它主要是由…嗯，我测试过的
• 🛠️ 积极发展 -事情可能会破裂、改变或让你感到惊讶

这意味着：

• ✅ 非常适合实验和学习
• ✅ 非常适合副项目和个人使用
• ✅ 如果你想贡献和塑造未来，那太棒了
• ❌ 可能还不适合关键生产系统
• ❌ 可能有bug、怪癖或“有趣”的行为
• ❌ 文档可能不完整或令人困惑

但最酷的部分是： 你可以帮助它变得更好！ 🚀 发现bug了吗？报告！想要一个功能？要求它！想贡献吗？我们很乐意！

*TL；DR：这是“早期访问”版本。使用风险自负，玩得开心，帮助我们让它变得棒极了！* 🎉

______________________________________________________________________

🎯 这是什么？

麦普金数据 是你的人工智能助手在数据工程方面的瑞士军刀。它暴露了 66+工具 通过MCP协议，让您的AI：

• 🔍 调试Kafka管道 不离开你的编辑
• 📊 查询数据库 （JDBC、Athena）并分析结果
• 🐼 处理数据 与pandas、polars和DuckDB合作
• ☁️ 与AWS合作 （雅典娜、S3、胶水）无缝衔接
• 🏗️ 检查基础设施 （Nomad，Consul）实时
• 📈 生成图表 自动生成证据包
• ✅ 验证数据质量 寄予厚望

这一切都不需要你写一行代码。 只需与你的AI聊天。🎉

______________________________________________________________________

⚡ 快速开始

安装

pip install -e ".[dev]"

运行服务器

python -m mcpkit.server

配置游标（或您的MCP客户端）

添加到光标MCP设置中：

{
  "mcpServers": {
    "mcpkit-data": {
      "command": "python",
      "args": ["-m", "mcpkit.server"],
      "env": {
        "MCPKIT_KAFKA_BOOTSTRAP": "localhost:9092",
        "MCPKIT_SCHEMA_REGISTRY_URL": "http://localhost:8081",
        "MCPKIT_JDBC_DRIVER_CLASS": "org.postgresql.Driver",
        "MCPKIT_JDBC_URL": "jdbc:postgresql://localhost/test",
        "MCPKIT_JDBC_JARS": "/path/to/postgresql.jar",
        "MCPKIT_ROOTS": "/allowed/path1:/allowed/path2"
      }
    }
  }
}

就是这样！ 您的AI现在可以使用所有66种以上的工具。 🎊

______________________________________________________________________

🛠️ 工具概述

📦 数据集注册表（4个工具）

你的数据的大本营。将数据集存储、查询和管理为Parquet文件。

______________________________________________________________________

🎧 Kafka工具（8个工具）

像专业人员一样调试、使用和分析Kafka主题。

______________________________________________________________________

📋 模式注册与解码（4个工具）

使用Avro、Protobuf和模式发现。

______________________________________________________________________

🗄️ 数据库工具（2个工具）

使用只读强制安全地查询数据库。

安全：自动阻止 DROP, INSERT, UPDATE, DELETE等等。 ✅

______________________________________________________________________

☁️ AWS工具（9个工具）

查询Athena，列出S3，管理Glue分区。

安全：默认情况下，SQL验证会阻止危险操作。 ✅

______________________________________________________________________

🐼 Pandas工具（12个工具）

数据科学家最好的朋友，现在是你的人工智能助手。

______________________________________________________________________

⚡ Polars工具（3个工具）

使用Polars进行闪电般快速的数据处理。

______________________________________________________________________

🦆 DuckDB工具（1个工具）

本地数据源上的SQL。不需要服务器。

______________________________________________________________________

🎨 JSON和数据质量（5个工具）

转换、验证和关联事件。

______________________________________________________________________

📁 文件和格式工具（4个工具）

处理文件并转换格式。

______________________________________________________________________

📊 可视化和证据（2个工具）

自动生成图表和证据包。

______________________________________________________________________

🏗️ 基础设施工具（8个工具）

监控Nomad的工作和领事服务。

模糊搜索：即使名称不完整，也能找到服务！ 🎯

______________________________________________________________________

🌐 HTTP工具（1个工具）

安全地发出HTTP请求。

安全：默认情况下禁用POST。需要选择加入。 ✅

______________________________________________________________________

✅ 远大期望（1个工具）

与GE进行数据质量验证。

______________________________________________________________________

🔄 对账（1个工具）

比较数据集并找出差异。

______________________________________________________________________

🔒 安全和护栏

🛡️ 内置安全

• 文件系统允许列表：所有文件操作仅限于 MCPKIT_ROOTS
• SQL验证：JDBC和Athena查询已验证（默认情况下为只读）
• HTTP安全：默认情况下禁用POST请求
• 输出限制：行、记录和字节的自动上限
• 路径横向保护：块 .. 以及不安全的路径

📏 可配置限制

______________________________________________________________________

⚙️ 配置

🔐 AWS凭据

AWS使用标准boto3证书链：

1. 环境变量 （推荐）：

   export AWS_ACCESS_KEY_ID=your-key
   export AWS_SECRET_ACCESS_KEY=your-secret
   export AWS_REGION=eu-central-1

1. AWS凭据文件 (~/.aws/credentials):

   [default]
   aws_access_key_id = your-key
   aws_secret_access_key = your-secret

1. IAM角色 （在EC2/ECS/Lambda上自动检测到）

1. AWS SSO （使用 aws sso login 第一）

📁 文件系统安全

export MCPKIT_ROOTS="/allowed/path1:/allowed/path2"

🎧 Kafka配置

export MCPKIT_KAFKA_BOOTSTRAP="localhost:9092"
export MCPKIT_KAFKA_SECURITY_PROTOCOL="SASL_SSL"  # optional
export MCPKIT_KAFKA_SASL_MECHANISM="PLAIN"  # optional
export MCPKIT_KAFKA_SASL_USERNAME="user"  # optional
export MCPKIT_KAFKA_SASL_PASSWORD="pass"  # optional

📋 模式注册表

export MCPKIT_SCHEMA_REGISTRY_URL="http://localhost:8081"
export MCPKIT_SCHEMA_REGISTRY_BASIC_AUTH="user:pass"  # optional

🗄️ 数据库

export MCPKIT_JDBC_DRIVER_CLASS="org.postgresql.Driver"
export MCPKIT_JDBC_URL="jdbc:postgresql://localhost/test"
export MCPKIT_JDBC_JARS="/path/to/postgresql.jar"
export MCPKIT_JDBC_USER="user"  # optional
export MCPKIT_JDBC_PASSWORD="pass"  # optional

______________________________________________________________________

🎯 示例工作流

🔍 端到端Kafka管道调试

你： 调试“订单事件”主题：使用最近的消息、解码Avro、过滤错误、分析模式并创建图表

AI回应：

I'll debug the order-events pipeline end-to-end.

[Step 1: kafka_consume_tail] Consuming last 50 messages...
✓ Consumed 50 messages from 'order-events'

[Step 2: schema_registry_get] Fetching Avro schema...
✓ Schema retrieved: order-event v2.3 (ID: 145)

[Step 3: avro_decode] Decoding Avro messages...
✓ Decoded 50 messages successfully

[Step 4: kafka_filter] Filtering error events...
✓ Found 8 error events matching criteria

[Step 5: pandas_groupby] Analyzing error patterns...
Error breakdown:
- Payment failures: 4 (50%)
- Validation errors: 2 (25%)
- Timeout errors: 2 (25%)

[Step 6: dataset_to_chart] Creating visualization...
✓ Chart saved: .artifacts/order_errors_analysis.png

[Step 7: pandas_export] Exporting error details...
✓ CSV exported: .artifacts/order_errors_20251221.csv

Summary: 8 errors out of 50 messages (16% error rate). Payment failures are the primary issue.

使用的工具： kafka_consume_tail → schema_registry_get → avro_decode → kafka_filter → pandas_groupby → dataset_to_chart → pandas_export （7工具）

______________________________________________________________________

📊 多源数据对账

你： 比较Athena和Postgres之间的销售数据：查询两者，在order_id上加入，查找差异，导出差异

AI回应：

I'll reconcile sales data between Athena and Postgres.

[Step 1: athena_start_query] Querying Athena sales table...
✓ Query started: execution_id abc123

[Step 2: athena_poll_query] Waiting for completion...
✓ Query completed in 3.2s (scanned 1.2 GB)

[Step 3: athena_get_results] Fetching results...
✓ Retrieved 5,234 rows from Athena

[Step 4: pandas_from_rows] Storing Athena data...
✓ Dataset created: athena_sales_20251221

[Step 5: db_query_ro] Querying Postgres sales table...
✓ Retrieved 5,189 rows from Postgres

[Step 6: pandas_from_rows] Storing Postgres data...
✓ Dataset created: postgres_sales_20251221

[Step 7: pandas_join] Joining datasets on order_id...
✓ Joined datasets: 5,180 matching orders

[Step 8: pandas_diff_frames] Finding discrepancies...
Discrepancies found:
- Missing in Postgres: 54 orders
- Missing in Athena: 9 orders
- Amount mismatches: 12 orders
- Total discrepancy value: $3,456.78

[Step 9: pandas_export] Exporting differences...
✓ Differences exported: .artifacts/sales_reconciliation_diff.csv

[Step 10: reconcile_counts] Generating reconciliation report...
✓ Report saved: .artifacts/sales_reconciliation_report.json

使用的工具： athena_start_query → athena_poll_query → athena_get_results → pandas_from_rows → db_query_ro → pandas_from_rows → pandas_join → pandas_diff_frames → pandas_export → reconcile_counts （10个工具）

______________________________________________________________________

🏗️ 服务健康调查

你： 调查“支付服务”：在Nomad中找到它，检查Consul运行状况，获取日志，过滤错误，与事件关联，并导出报告

AI回应：

I'll investigate the payment-service health comprehensively.

[Step 1: nomad_list_jobs] Finding payment-service...
✓ Found: platform-payment-service-app (status: running)

[Step 2: nomad_get_job_status] Getting job details...
✓ Job running on node: node-abc-123
✓ Allocation: alloc-def-456

[Step 3: consul_get_service_health] Checking Consul health...
✓ Service health: passing (3/3 checks passing)
✓ Service IPs: 10.0.1.45:8080, 10.0.1.46:8080

[Step 4: nomad_get_allocation_logs] Retrieving logs...
✓ Retrieved last 200 log lines

[Step 5: pandas_from_rows] Storing logs as dataset...
✓ Dataset created: payment_service_logs

[Step 6: pandas_filter_query] Filtering error logs...
✓ Found 15 error entries in last hour

[Step 7: kafka_consume_batch] Consuming related events...
✓ Consumed 100 payment events from Kafka

[Step 8: event_correlate] Correlating logs with events...
✓ Correlated 12 error logs with payment events

[Step 9: pandas_groupby] Analyzing error patterns...
Error analysis:
- Database timeouts: 8 (53%)
- External API failures: 4 (27%)
- Validation errors: 3 (20%)

[Step 10: evidence_bundle_plus] Generating evidence bundle...
✓ Bundle created:
  - .artifacts/payment_service_investigation_stats.json
  - .artifacts/payment_service_error_logs.csv
  - .artifacts/payment_service_correlated_events.csv

Summary: Service is healthy but experiencing intermittent database timeouts affecting 8 transactions.

使用的工具： nomad_list_jobs → nomad_get_job_status → consul_get_service_health → nomad_get_allocation_logs → pandas_from_rows → pandas_filter_query → kafka_consume_batch → event_correlate → pandas_groupby → evidence_bundle_plus （10个工具）

______________________________________________________________________

✅ 数据质量验证管道

你： “验证Kafka事件：使用批处理、展平嵌套JSON、根据模式验证、检查数据质量并生成报告”

AI回应：

I'll run a complete data quality validation on Kafka events.

[Step 1: kafka_consume_batch] Consuming event batch...
✓ Consumed 500 messages from 'user-actions' topic

[Step 2: kafka_flatten] Flattening nested JSON structures...
✓ Flattened 500 records into 45 columns
✓ Dataset created: user_actions_flattened

[Step 3: schema_registry_get] Fetching validation schema...
✓ Retrieved JSONSchema: user-action-event v1.2

[Step 4: pandas_sample_random] Sampling for validation...
✓ Sampled 50 random records

[Step 5: event_validate] Validating against schema...
Validation results:
- Valid records: 47 (94%)
- Invalid records: 3 (6%)
  - Missing required field 'timestamp': 2
  - Invalid enum value 'action_type': 1

[Step 6: pandas_schema_check] Checking data types and constraints...
✓ Schema check passed: all required columns present
⚠️ Warning: 12% null values in 'metadata' column

[Step 7: pandas_count_distinct] Analyzing data quality...
Distinct value counts:
- user_id: 234 unique (expected: ~250)
- action_type: 8 distinct (expected: 10)
- session_id: 198 unique

[Step 8: pandas_filter_time_range] Filtering recent events...
✓ Filtered to last 24 hours: 487 events

[Step 9: great_expectations_check] Running GE validation suite...
✓ Expectations passed: 8/10
⚠️ Failed: 
  - expect_column_values_to_be_unique (user_id)
  - expect_column_values_to_not_be_null (metadata)

[Step 10: evidence_bundle_plus] Generating quality report...
✓ Quality report: .artifacts/data_quality_report_20251221.zip

使用的工具： kafka_consume_batch → kafka_flatten → schema_registry_get → pandas_sample_random → event_validate → pandas_schema_check → pandas_count_distinct → pandas_filter_time_range → great_expectations_check → evidence_bundle_plus （10个工具）

______________________________________________________________________

📈 时间序列分析与预测

你： 分析销售趋势：查询过去6个月的Athena，按日期范围过滤，按周分组，质量抽样，创建图表，导出

AI回应：

I'll analyze sales trends over the last 6 months.

[Step 1: athena_start_query] Starting sales query...
✓ Query: SELECT * FROM sales WHERE date >= '2025-06-01'

[Step 2: athena_poll_query] Monitoring execution...
✓ Query running... (scanned 2.1 GB so far)

[Step 3: athena_get_results] Fetching results...
✓ Retrieved 45,678 sales records

[Step 4: pandas_from_rows] Storing in dataset...
✓ Dataset created: sales_6months

[Step 5: pandas_filter_time_range] Filtering date range...
✓ Filtered: 2025-06-01 to 2025-12-21 (45,234 records)

[Step 6: pandas_groupby] Grouping by week and region...
✓ Aggregated: 26 weeks × 4 regions = 104 groups

[Step 7: pandas_sample_stratified] Stratified sampling...
✓ Sampled 20 records per region for validation

[Step 8: pandas_describe] Statistical analysis...
Statistics:
- Total sales: $12,345,678
- Average per week: $474,833
- Trend: +5.2% week-over-week
- Peak week: Week 24 ($567,890)

[Step 9: dataset_to_chart] Creating time-series chart...
✓ Chart: .artifacts/sales_trends_6months.png

[Step 10: pandas_export] Exporting aggregated data...
✓ Exported: .artifacts/sales_by_week_region.csv (104 rows)
✓ Exported: .artifacts/sales_statistics.json

使用的工具： athena_start_query → athena_poll_query → athena_get_results → pandas_from_rows → pandas_filter_time_range → pandas_groupby → pandas_sample_stratified → pandas_describe → dataset_to_chart → pandas_export （10个工具）

______________________________________________________________________

🔄 跨系统事件关联

你： 跨系统关联用户事件：获取Kafka事件、查询数据库以获取用户配置文件、连接数据集、重复数据删除、关联时间戳和导出

AI回应：

I'll correlate user events across Kafka and database systems.

[Step 1: kafka_consume_batch] Consuming user events...
✓ Consumed 1,000 events from 'user-events' topic

[Step 2: kafka_flatten] Flattening event structure...
✓ Flattened to 1,000 records with 32 columns

[Step 3: db_query_ro] Querying user profiles...
✓ Retrieved 850 user profiles from database

[Step 4: pandas_from_rows] Storing profiles...
✓ Dataset created: user_profiles

[Step 5: pandas_join] Joining events with profiles...
✓ Joined on user_id: 987 matched records

[Step 6: dedupe_by_id] Removing duplicate events...
✓ Deduplicated: 23 duplicates removed (964 unique)

[Step 7: event_correlate] Correlating by timestamp...
✓ Correlated events into 234 user sessions

[Step 8: pandas_groupby] Analyzing session patterns...
Session analysis:
- Average session duration: 12.5 minutes
- Events per session: 4.1
- Most active users: 12 users with 10+ events

[Step 9: pandas_filter_query] Filtering high-value sessions...
✓ Found 45 sessions with purchase events

[Step 10: pandas_export] Exporting correlated data...
✓ Exported: .artifacts/correlated_user_sessions.csv
✓ Exported: .artifacts/session_analysis.json

使用的工具： kafka_consume_batch → kafka_flatten → db_query_ro → pandas_from_rows → pandas_join → dedupe_by_id → event_correlate → pandas_groupby → pandas_filter_query → pandas_export （10个工具）

______________________________________________________________________

🧪 测试

快速开始

# Run all tests
pytest

# Run unit tests only (no Docker required)
make test-unit

# Run integration tests (requires Docker)
make test-integration

# Run with coverage
make test-coverage

覆盖

# Run tests with coverage
make test-coverage

# Generate HTML report
make coverage-html
open htmlcov/index.html

目标：核心模块覆盖率为95%。看 tests/COVERAGE.md 了解详情。

所有测试都使用Docker容器来提供外部服务（Kafka、PostgreSQL、LocalStack、Consul、Nomad）。不需要真正的AWS凭据！ ✅

🔄 代码更改后重新加载MCP服务器

当您修改MCP工具代码时（例如。， mcpkit/core/*.py 或 mcpkit/server.py)，Cursor需要重新加载MCP服务器以获取您的更改。

快速重新加载：

./reload_mcp_server.sh

此脚本修改您的Cursor MCP配置文件以触发自动重新加载。如果自动重新加载不起作用，请手动重新启动Cursor。

何时重新加载：

• ✅ 在中编辑工具实现后 mcpkit/core/*.py
• ✅ 在中添加/修改工具后 mcpkit/server.py
• ✅ 更改工具文档或参数后
• ❌ 配置更改不需要（环境变量）

手动重新加载替代方案：

1. 打开光标设置→ MCP
2. 暂时禁用 mcpkit-data 服务器
3. 重新启用它
4. 游标将重新加载服务器

______________________________________________________________________

🤝 贡献

我们❤️ 贡献！以下是如何提供帮助：

1. 🐛 发现bug了吗？ 打开一个问题
2. 💡 有主意吗？ 提出新的工具或功能
3. 🔧 想编码吗？ 结账 TOOLS_ANALYSIS.md 对于差距
4. 📝 文件不清楚？ 改进它们！

设计原则：

• 🎯 保持简单：一个工具，一份工作
• 🔗 可组合：工具无缝协作
• 🔒 安全：默认情况下为只读，明确选择加入
• ⚡ 快：高效操作，智能限制

______________________________________________________________________

📚 了解更多

• 模型上下文协议 -我们使用的协议
• FastMCP -我们构建的框架
• 光标 -使其大放异彩的IDE✨

______________________________________________________________________

📄 许可证

MIT许可证-使用它，分叉它，让它变得更好！ 🚀

______________________________________________________________________

制作❤️ 适用于希望更快发货的数据工程师

*停止上下文切换。开始发货。* 🎯