Skip to main content
Glama
BitDG

TableRAG

by BitDG
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

TableRAG

TableRAG 将 .xls、.xlsx、.xlsm 和 .csv 文件夹构建成本地语义目录。它在 DuckDB 中保留精确记录，识别字段、规则和跨表关系，并通过 MCP、CLI 与本地 Web 工作台提供确定性的只读查询。

无需模型或 Embedding 服务。项目路径、表格约定和人工确认的领域知识都保存在 YAML 中，不会硬编码进 Python 包。

快速开始 · 工作原理 · AI 接入指南 · 配置参考 · 安全策略

为什么需要 TableRAG

表格使用中的问题

TableRAG 的处理方式

AI 每次都要重新打开并解析大量工作簿

使用 SHA-256 增量索引，形成可复用的本地目录

不同文件的表头行和字段含义不一致

自动检测，并支持按 Sheet 显式确认语义布局

搜索结果脱离原始表格，无法复核

保留工作簿、Sheet、行、列和单元格证据

相似字段名容易形成错误关联

候选关系与人工验证关系严格分开

切换 Git 分支后配置数据互相污染

可选的分支隔离 DuckDB 目录

业务表格包含敏感数据

源表只保留在本地，TableRAG 永不修改源文件

Related MCP server: mcp-tabular

你会得到什么

  • 精确记录查询、字段过滤、表发现、规则搜索和关系追踪。

  • 跨 Schema、注释、规则、关系与记录的统一证据搜索。

  • 验证候选主键，而不是默认第一列必然唯一。

  • 显式规则和推断规则分别保存，并携带置信度与单元格证据。

  • 可配置字段名、中文注释、英文说明、字段类型和项目元数据所在行。

  • 从指定目录或自动发现的 strings/cn 目录加载正式名称与本地化文本。

  • Excel / WPS 保存后的防抖增量更新，以及单写入者索引队列。

  • 字段级人工知识，区分候选、已验证和已废弃状态。

  • 支持本地 stdio、Streamable HTTP 和兼容 SSE 的只读 MCP。

  • 用于范围确认、表格预览、布局修复、诊断、知识审核和构建的本地 Web 工作台。

工作原理

flowchart LR
    A["表格文件夹"] --> B["范围与布局规则"]
    B --> C["解析与诊断"]
    C --> D["DuckDB 语义目录"]
    K["人工验证的项目知识"] --> D
    D --> E["CLI"]
    D --> F["只读 MCP"]
    D --> G["本地 Web 工作台"]
    F --> H["AI 客户端"]

目录中保存规范化记录、Schema 元数据、规则、关系、本地化信息和可搜索语义文档。 所有检索结果都能回到源表证据；TableRAG 不会写入源表。

快速开始

需要 Python 3.10+ 和 uv。

Windows 用户可以双击 start.bat 打开本地配置工作台，也可以直接执行：

cd C:\path\to\TableRAG
uv sync --extra dev
uv run table-rag init C:\path\to\spreadsheet-folder `
  --output projects\my-project.local.yaml `
  --name "My Project"
uv run table-rag web --project projects\my-project.local.yaml

在 Web 工作台中依次完成：

  1. 确认数据目录、文件类型、递归范围、需要处理的 Sheet 和排除列。

  2. 预览工作簿，确认或修复语义行布局。

  3. 处理阻塞诊断，防止结构异常的表进入当前目录。

  4. 构建索引并复制生成的 MCP 配置。

需要自动化时可以直接使用 CLI：

uv run table-rag build --project projects\my-project.local.yaml
uv run table-rag doctor --project projects\my-project.local.yaml
uv run table-rag query --project projects\my-project.local.yaml --table item --id 1001
uv run table-rag rag --project projects\my-project.local.yaml --query "查找道具字段和记录"
uv run table-rag watch --project projects\my-project.local.yaml

本地项目文件使用 .local.yaml 后缀，并已被 Git 忽略。

连接 AI 客户端

本地桌面客户端优先使用 stdio：

{
  "mcpServers": {
    "TableRAG": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\TableRAG",
        "run",
        "table-rag",
        "mcp",
        "--project",
        "C:\\path\\to\\TableRAG\\projects\\my-project.local.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

本机 Streamable HTTP：

uv run table-rag mcp `
  --project projects\my-project.local.yaml `
  --transport streamable-http `
  --host 127.0.0.1 `
  --port 8765

端点为 http://127.0.0.1:8765/mcp。除非外部已经配置身份验证、TLS 和明确的网络策略， 否则应始终保持 localhost 监听。完整交接、验证与查询路由见 AI 接入指南。

MCP 查询面

用途

MCP 工具

项目与 Schema 发现

get_project、list_tables、find_tables、describe_table、describe_column

精确记录

get_record、get_records_by_field、search_records

语义检索

search_knowledge、search_project_knowledge、search_rules

关系与解释

trace_relations、get_field_knowledge、explain_record

所有工具均为只读。规则会说明它是显式规则还是推断规则，并返回置信度和 orders.xlsx#Sheet1!F1 形式的源证据。

安全边界

  • 源表是只读输入，TableRAG 永不修改源表。

  • 本地项目 YAML、DuckDB 目录、基准原始输出和构建产物均被 Git 忽略。

  • Web 工作台只监听 localhost，并将预览路径限制在已确认的数据范围内。

  • 表格显式规则、人工知识和统计推断始终可以区分。

  • 已验证关系在进入普通语义搜索前，会对当前分支目录进行字段检查。

暴露 MCP 端点或分享仓库快照前，请阅读 SECURITY.md。

文档

文档

用途

AI 接入指南

可复制的 MCP 配置、验证步骤和查询路由

配置参考

数据源、布局、本地化、分支、Watcher 与项目知识

贡献指南

开发环境、测试、PR 和数据安全规则

安全策略

私密报告方式和部署边界

开发

uv sync --extra dev --locked
uv run pytest
uv build
uv run python scripts\check_repository_secrets.py --include-untracked

默认 VS Code 构建任务会运行测试并构建 wheel。CI 覆盖 Windows、Linux 和受支持的 Python 版本。

许可证

Apache License 2.0

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • tablebridge

    Michael-WhiteCapData
    A
    license
    A
    quality
    B
    maintenance
    Turns a folder of CSV, Parquet, and JSON files into a single SQL-queryable source for AI agents, supporting JOINs across files with read-only sandboxed access.
    6
    2
    MIT

  • mcp-tabular

    ayushsri
    A
    license
    B
    quality
    C
    maintenance
    Enables SQL querying over CSV and Excel files using DuckDB, providing tools to load files, inspect schemas, and run read-only queries via MCP.
    5
    MIT

  • autokg

    kaushikthakur97
    A
    license
    Not graded
    quality
    B
    maintenance
    Turns warehouse/lakehouse tables into a governed entity-relationship knowledge graph exposed through MCP, enabling AI agents to answer multi-table business questions without hard-coded SQL or large schema prompts.
    Apache 2.0

  • vault-mcp

    nikhgupta
    A
    license
    Not graded
    quality
    D
    maintenance
    Turn any folder into a searchable knowledge base for AI, exposed via MCP.
    1
    MIT