Skip to main content
Glama
agent-gateway

agent-gateway

by yongpange

企业数据与知识 Agent 接入网关

把磁盘上的异构文件编目成 Agent 可调用的工具契约(MCP + 独立 CLI)。
这不是阿里式数据中台;生产上把 DuckDB 换成 Doris/Hive 时,工具名和参数可以保持不变。

  • 知识层:本机生财 JSON 语料(不进 Git)+ 仓库内 3 篇自写 SOP

  • 业务层:180 天合成电商数仓(CSV / XLSX / Parquet → DuckDB)

  • 12 个工具:kb_* / biz_* / catalog_*,设计语言对齐 scys MCP(何时用、ID 链、分页、禁猜 ID)

快速开始

cd D:\SCYS-data\gateway
uv venv --python 3.12.13 .venv
uv pip install -p .venv -e ".[dev]"
.\.venv\Scripts\agent-gateway-ingest
.\.venv\Scripts\agent-gateway demo
.\.venv\Scripts\agent-gateway-eval

在线模型(可选):复制 .env.example 为 .env,填 OpenAI 兼容网关,然后:

.\.venv\Scripts\agent-gateway ask "上周 GMV 最高的 SKU 有没有对应 SOP?" --live

Cursor 里装 MCP:参考 docs/cursor.mcp.example.json。

Related MCP server: MetaGraph-MCP

工具地图

前缀

工具

作用

kb

list_tags / search / get_doc / get_outline / read_section

标签 → 检索 → 分页正文

biz

list_metrics / query_sales / get_sku / get_order / anomaly_scan

结构化过滤,禁止任意 SQL

catalog

list_assets / lineage

资产与血缘

跨层演示(agent-gateway demo):

  1. 上周 GMV 最高 SKU → 3C 充电 SOP

  2. 音频退款率异常 → 售后复盘

  3. 抖音花费升、转化平 → 投放排查清单

目录

gateway/
  src/agent_gateway/   # 接入、存储、工具、MCP、CLI Agent、评测
  fixtures/internal_sops/  # 可公开的自写 SOP
  eval/cases.yaml      # 20 道离线黄金题
  docs/INTERVIEW.md    # 面试讲稿

生成物在 .local/(已 gitignore)。社区 JSON 原文只留在 D:\SCYS-data,不要提交。

简历表述

设计并实现企业数据/知识 MCP 网关与独立 Agent:将磁盘侧多格式文档与主题域指标以工具契约暴露;支持检索、口径查询、异常扫描与跨源引用。演示语料为社区知识库 + 合成电商数仓,接口按可替换生产引擎设计。

面试怎么讲见 docs/INTERVIEW.md。

Available Tools

12 tools
biz_anomaly_scanA

【异常扫描】对 GMV / 退款率 / 投放转化做环比。

【metric】gmv = SKU 近 14 日 GMV 相对前 14 日;refund_rate = 2026-08 vs 2026-07 类目退款率; ad_cvr = 2026-08-31..09-13 vs 前两周,渠道花费与转化。 【何时用】「有什么异常」「退货率是不是高了」「投放涨了转化没涨」。 【跨层】拿到 category / sku 名后,用 kb_search 找对应 SOP / 复盘,禁止编造内部文档。

Inputs: metric (required), end_date. Returns: object

biz_get_orderA

【订单详情】按 order_id 取一单。intern 角色会被拒绝。

【参数从哪来】order_id 形如 ORD-100123,必须来自查询结果,禁止枚举。

Inputs: order_id (required). Returns: object

biz_get_skuA

【SKU 详情】按 sku_id 取商品维表。

【参数从哪来】sku_id 必须来自 biz_query_sales / biz_anomaly_scan,禁止猜。

Inputs: sku_id (required). Returns: object

biz_list_metricsA

【指标字典】列出业务层可查询指标、口径、粒度和敏感级。

【何时用】不确定有哪些数、别直接猜表名时先摸地图。 【何时不用】已经明确要查 GMV/退款/花费 → biz_query_sales 或 biz_anomaly_scan。 【禁止】本工具不执行任意 SQL,也不返回底层表结构以外的口径说明。

Inputs: no named parameters. Returns: object

biz_query_salesA

【销售查询】按结构化过滤汇总 GMV / 订单 / 退款率。

【硬约束】只能用本工具的过滤字段,禁止拼接 SQL。 【group_by】day / week / sku / category / channel / shop。 【ID 从哪来】sku_id 来自结果或 biz_get_sku;shop_id 为 SHOP-TM / SHOP-DY / SHOP-OS; channel_id 为 tmall / douyin / independent / xiaohongshu。不要编造 SKU。 【金额】gmv_cent 为分,展示时除以 100。 【何时用】「上周哪个 SKU GMV 最高」「音频类目 8 月退款率」。 【何时不用】只要异常对比 → biz_anomaly_scan;只要单订单 → biz_get_order。

Inputs: limit, sku_id, shop_id, category, +4 more. Returns: object

catalog_lineageA

【血缘】查看某一资产从源文件到表/文档再到工具的链路。

【参数从哪来】asset_id 必须来自 catalog_list_assets.items[i].asset_id。 【何时用】面试或排障时解释「这份 Excel 怎么变成可查询指标」。

Inputs: asset_id (required). Returns: object

catalog_list_assetsA

【资产目录】列出当前接入的数据/知识资产:格式、行数、敏感级、位置。

【何时用】用户问「现在接了哪些数据」「磁盘上有什么」「有没有订单表」。 【何时不用】要查数走 biz_*,要搜文档走 kb_*。

Inputs: no named parameters. Returns: object

kb_get_docA

【文档正文】按 doc_id 读取单篇正文(分页)。

【参数从哪来】doc_id 必须来自 kb_search.items[i].doc_id,禁止用标题猜。 【分段】默认最多 4000 字;truncated=true 时把 next_offset 原样传入继续读。 【飞书空洞】feishu_stub_only=true 时 readable=false,body 只有导语,不得当成全文。 【何时用】已经拿到 doc_id,用户要看原文/摘要/引用。

Inputs: doc_id (required), offset, max_chars. Returns: object

kb_get_outlineA

【第 1 步·文档目录】按 doc_id 返回章节树(标题 + offset + section_id)。

【何时用】长 SOP / 复盘要按章阅读,或准备调用 kb_read_section。 【参数从哪来】doc_id 来自 kb_search。section_id / offset 交给 kb_read_section。 【短文】可能只有一个「全文」节点,此时直接 kb_get_doc 即可。

Inputs: doc_id (required). Returns: object

kb_list_tagsA

【常用标签清单】列出知识库当前标签(按文档数倒序)。

【何时用】想按标签检索但不确定有哪些标签时,先调本工具拿 tag_id / name, 再把 name 传给 kb_search.tag_names。【不要】用本工具读正文。

Inputs: no named parameters. Returns: object

kb_read_sectionA

【第 2 步·读某一章】按 section_id 或 outline 返回的 offset 读取一节。

【必须先调 kb_get_outline】section_id 只能取自同一次目录的 sections[i].section_id。 也可把 sections[i].offset 传入 offset。交叉使用别的文档的 section_id 会失败。

Inputs: doc_id (required), offset, max_chars, section_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation4/5

    The knowledge base tools (kb_list_tags, kb_search, kb_get_doc, kb_get_outline, kb_read_section) have a clear hierarchical flow (search -> outline -> read), and the business tools (biz_list_metrics, biz_query_sales, biz_get_sku, biz_get_order, biz_anomaly_scan) are distinct operationally. Minor overlap exists between kb_get_doc and kb_read_section, both for reading content, but guidance on when to use each is provided.

    Naming Consistency4/5

    Tool names are consistent, following a verb_noun pattern with prefixes indicating domain (kb_, biz_, catalog_). Most use standard verbs like list, get, read, search, query, and anomaly_scan is a slight deviation but still readable.

    Tool Count4/5

    With 12 tools, the server covers three distinct domains (knowledge, business, catalog) without excessive granularity. The count is reasonable and each tool serves a clear purpose, though it is a bit high for the scope, justifying a slightly lower score.

    Completeness3/5

    The server offers a comprehensive read/search surface for knowledge (tag, search, outline, section, full doc) and metrics (dictionary, query, SKU, order, anomaly scan), but lacks write or update tools (no create/edit/delete). This is acceptable if it's a fetch-only gateway, but for general lifecycle coverage it's incomplete.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to query live schema, lineage, and query-context across data warehouses, dbt projects, orchestration systems, and BI tools via MCP tools.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables enterprise AI agents to query governed data lineage, PII-aware schema documentation, and semantic metadata from SQL logs via MCP, with role-based access and vector search.
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Enables AI agents to query an air-gapped enterprise knowledge vault via seven MCP tools for deterministic and hybrid retrieval, entity graph traversal, context compression, archive inspection, onboarding scans, and node status.
      7
      -