MCP Data Scout

MCP数据侦察员

A. 数据发现工具 构建为MCP（模型上下文协议）服务器。 允许AI代理和人类在多个数据源（CSV/Sqlite）中搜索表、列和数据，并能够上传新的数据源。

📋 导航

• 快速开始
• MCP快速测试
• 建筑

- 组件分解

• 种子数据描述
• 添加您自己的数据

- 通过Web UI - 索引规则JSON

• MCP工具

- list_sources() - index_source(source_id) - search(query, limit?, source_ids?, match_types?) - get_schema(source_id, path)

• REST API
• 连接AI代理

- 克劳德桌面/光标

• 项目结构
• 环境变量
• 搜索索引设计

______________________________________________________________________

快速开始

git clone https://github.com/ArgentumX/mcp-data-scout.git

cd mcp-data-scout

cp .env.example .env

docker compose up --build

• 流线型UI: http://localhost:8501
• REST API/MCP服务器: http://localhost:8000
• API文件: http://localhost:8000/docs

首次启动时，如果env var SEED为“true”（SQLite+CSV），服务器会自动生成示例数据。 进入 MASTER_API_KEY 从 .env 到现场

然后单击 “索引所有来源” 在前端侧边栏中为它们建立索引。

alt text alt text alt text

MCP快速测试

启动mcp数据侦察（快速启动）

cd mcp-test

docker build -t mcp-data-scout-test .

docker run --network host mcp-data-scout-test

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────┐
│                   Docker Compose                     │
│                                                     │
│  ┌──────────────────┐      ┌──────────────────────┐ │
│  │   data-scout-ui  │      │   data-scout-mcp     │ │
│  │   (Streamlit)    │─────▶│   (FastAPI + MCP)    │ │
│  │   port 8501      │ HTTP │   port 8000          │ │
│  └──────────────────┘      └──────────┬───────────┘ │
│                                       │             │
│                             ┌─────────▼──────────┐  │
│                             │   /data  (volume)  │  │
│                             │   uploads/         │  │
│                             │   sqlite_main.db   │  │
│                             │   *.csv            │  │
│                             │   index.db (FTS5)  │  │
│                             │   sources.json     │  │
│                             └────────────────────┘  │
└─────────────────────────────────────────────────────┘

组件分解

______________________________________________________________________

种子数据描述

______________________________________________________________________

添加您自己的数据

通过Web UI

打开 添加源 Streamlit UI中的选项卡：

1. csv文件 --上传任意 .csv 文件，给它一个唯一的源ID，并可选地提供JSON格式的索引规则。
2. SQLite数据库 --上传a .db / .sqlite 文件，给它一个唯一的源ID，并可选地提供索引规则。

上传的文件存储在 /data/uploads/ 由于 来源清单 /data/sources.json.

上传后，点击 立即索引 在侧边栏中的新源代码旁边。

索引规则JSON

每个上传的源都可以有自己的索引规则来控制索引的内容 以及行值是否可搜索。所有字段都是可选的。

{
  "include_tables": ["sales", "products"],
  "exclude_tables": ["logs", "audit"],
  "exclude_columns": {
    "users": ["password_hash", "token"]
  },
  "row_value_tables": ["products", "orders"],
  "row_value_columns": {
    "products": ["name", "category"],
    "orders": ["status", "shipping_city"]
  }
}

留空或 {} 无限制地索引所有内容。

______________________________________________________________________

MCP工具

服务器在以下位置公开MCP工具 http://localhost:8000/mcp/sse:

list_sources()

返回所有具有索引状态的已注册数据源。

[
  {
    "source_id": "sqlite_main",
    "source_type": "sqlite",
    "description": "Main SQLite database with business data",
    "location": "/data/uploads/sqlite_main.db",
    "is_indexed": true
  }
]

index_source(source_id)

从源读取模式并将元数据存储在FTS5索引中。

{ "success": true, "source_id": "sqlite_main", "tables_indexed": 5 }

search(query, limit?, source_ids?, match_types?)

在表名、列名和索引行值之间进行全文搜索。 返回按匹配类型分组的排名结果（表→ 列→ row).

[
  {
    "match_type": "table",
    "source_id": "sqlite_main",
    "table_name": "customers",
    "row_count": 200,
    "columns": [{"name": "email", "data_type": "TEXT", "sample_values": ["..."]}]
  }
]

get_schema(source_id, path)

返回特定表的完整列架构+5个示例行。

{
  "success": true,
  "table_name": "orders",
  "row_count": 500,
  "columns": [...],
  "sample_rows": [...]
}

______________________________________________________________________

REST API

______________________________________________________________________

连接AI代理

克劳德桌面/光标

添加到MCP配置中：

{
  "mcpServers": {
    "type": "sse",
    "data-scout": {
      "url": "http://localhost:8000/mcp/sse"
    },
    "headers": {
      "X-API-KEY": "DEV_MASTER_API_KEY"
    }
  }
}

然后，代理可以呼叫：

list_sources()
index_source("sqlite_main")
search("customer email")
get_schema("sqlite_main", "customers")

______________________________________________________________________

项目结构

mcp-data-scout/
├── backend/
│   ├── connectors/
│   │   ├── abstraction/base.py      # BaseConnector, IndexingRules, data models
│   │   ├── csv_connector.py         # Single-file CSV connector
│   │   └── sqlite_connector.py      # SQLite connector
│   ├── index/
│   │   └── indexer.py               # SQLite FTS5 metadata indexer
│   ├── search/
│   │   └── engine.py                # Full-text search engine
│   ├── server/
│   │   ├── api_app.py               # FastAPI REST endpoints (incl. upload)
│   │   ├── config.py                # Environment config
│   │   ├── mcp_app.py               # FastMCP tool definitions
│   │   ├── server.py                # Combined server entry point
│   │   ├── services.py              # Shared singletons (registry, indexer, engine)
│   │   └── source_registry.py       # ManagedRegistry + manifest persistence
│   └── scripts/
│       ├── seed_data.py             # Generates sample SQLite + CSV data
│       └── entrypoint.sh            # Docker entrypoint
├── frontend/
│   └── app.py                       # Streamlit web UI
├── docker-compose.yml
├── .env.example
└── requirements.txt

______________________________________________________________________

环境变量

______________________________________________________________________

搜索索引设计

元数据存储在 SQLite FTS5 虚拟表——一个内置的全文搜索引擎，没有外部依赖关系。

三个索引实体：

• table_fts — source_id, source_type, table_name, path
• column_fts — source_id, table_name, column_name, data_type
• row_fts — source_id, table_name, row_text （连接索引列值）

搜索策略（优先级顺序）：

1. FTS5前缀匹配——快速，按BM25相关性排名
2. LIKE %query% 回退--捕获部分中间词匹配