录取数据飞书多维表格 MCP

这个 MCP 给 AstrBot 提供招生录取数据查询、聚合和跨表对比能力。机器人只拿到 MCP 处理后的统计结果，不需要把多维表格大表原始数据塞进上下文。

示例配置支持 5 个数据集：

• admission_2026：26录取数据表

• admission_2021_2025：21-25录取数据表

• plan_2025：25计划表

• plan_2026：26计划表

• score_rank_2026_primary：26一分一段表

核心原则：

• 字段来自飞书表格实时字段列表，字段写错会直接报错并给相近字段建议。

• 每张表有自己的字段别名映射，例如 school 在 26 录取表对应 匹配中学，在 21-25 录取表对应 中学。

• 聚合工具会扫描完飞书返回的所有匹配记录后再返回；如果飞书接口失败，不返回半截统计。

• 数值聚合用 Decimal 计算，结果以字符串返回，避免浮点误差。

• 默认不允许返回敏感字段；如内部使用可设置 ADMISSION_MCP_ALLOW_SENSITIVE_FIELDS=true。

• 所有工具都要求由 AstrBot 飞书事件上下文注入 requester_id，服务端据此检查显式读取、写入、运维和特定能力权限。

1. 配置

.env 至少需要：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_APP_TOKEN=base_or_bitable_token
ADMISSION_MCP_ALLOW_SENSITIVE_FIELDS=false

先复制公开仓库中的示例文件，再填入你自己的飞书配置：

cp .env.example .env
cp config/datasets.example.json config/datasets.json
cp admission-permissions.example.json admission-permissions.json

上述三个运行时文件已被 .gitignore 排除，请勿提交真实凭据、表格 ID、人员姓名或 Open ID。

四张表的 table_id、view_id 和字段别名放在：

config/datasets.json

如果配置文件不在默认位置，可以设置：

ADMISSION_DATASETS_CONFIG=/path/to/datasets.json

权限由 admission-permissions.json 和 admission-tool-permissions.json 管理。系统仅保留三种招办角色，实际读、写和运维权限以人员配置中的显式开关为准，详见 PERMISSIONS.md。

Related MCP server: Feishu MCP Server

2. 启动 MCP

本服务使用 MCP stdio 方式：

python -m pip install -r requirements.txt
python run_mcp.py

AstrBot 的 MCP 配置形态类似：

{
  "mcpServers": {
    "admission-feishu": {
      "command": "python3",
      "args": ["/AstrBot/data/mcp/admission-feishu/run_mcp.py"],
      "active": true
    }
  }
}

3. 工具

admission_config_check

检查配置和数据集状态。ping_feishu=true 时会对每个数据集做最小只读查询。

admission_schema

查看指定数据集的字段、别名、敏感字段和支持操作。

示例：

{"requester_id": "ou_from_event_context", "dataset": "admission_2021_2025"}

admission_send_student_photo

按姓名或学号精确查询 admission_2026 的学生记录，并将“个人照片”附件通过机器人私聊发送给当前查询人。图片只在内存中完成多维表格素材下载和飞书 IM 图片上传，不写入本地临时文件。姓名存在重名时不会发送，需改用学号。

示例：

{
  "requester_id": "ou_from_event_context",
  "identifier": "202600001"
}

admission_query

查询少量明细。dataset 留空时默认查 admission_2026，兼容旧用法。

示例：

{
  "requester_id": "ou_from_event_context",
  "dataset": "admission_2021_2025",
  "filters": [
    {"field": "year", "op": "eq", "value": 2025},
    {"field": "school", "op": "contains", "value": "南通中学"}
  ],
  "fields": ["year", "province", "school", "major", "score", "rank"],
  "limit": 20
}

admission_aggregate

单表聚合，适合人数、分布、最高/最低/平均分、计划数。

示例：查 2025 年南通中学录取人数和分数统计：

{
  "requester_id": "ou_from_event_context",
  "dataset": "admission_2021_2025",
  "filters": [
    {"field": "year", "op": "eq", "value": 2025},
    {"field": "school", "op": "contains", "value": "南通中学"}
  ],
  "metrics": [
    {"name": "人数", "op": "count"},
    {"name": "最低投档成绩", "op": "min", "field": "score"},
    {"name": "最高投档成绩", "op": "max", "field": "score"},
    {"name": "平均投档成绩", "op": "avg", "field": "score"}
  ]
}

计划表如果不传 metrics，默认按 PlanNUM 汇总为 计划数。

admission_zodiac_distribution

按指定年份统计十二星座录取人数。星座由 MCP 在内部使用“出生月份”和“出生日”计算，只返回汇总人数和无效日期数量，不返回生日明细。可通过 filters 继续限定省份、中学、专业或书院。

{
  "requester_id": "ou_from_event_context",
  "year": 2026,
  "filters": [
    {"field": "province", "op": "eq", "value": "江苏"}
  ]
}

admission_score_rank

查询 2026 年某省某分数对应的一分一段位次区间。province 和 score 必填，subject 可选；科类名称按省份考试模式区分：新疆返回“文史/理工”，新高考省份返回“历史类/物理类”，综合改革省份返回“综合改革”。工具会按省份自动转换“文科”“理科”等简称。

{
  "requester_id": "ou_from_event_context",
  "province": "江苏",
  "score": 650,
  "subject": "物理类"
}

admission_college_rank

计算指定年份目标书院的平均投档成绩排名。MCP 会在内部使用全部书院数据完成排名，但只返回目标书院的平均分、名次、参评书院数和样本量，不返回其他书院的名称或统计值。调用者需要显式配置 benchmark.college_rank 能力。

admission_multi_aggregate

一次执行多个聚合请求，适合同时取多个年份或计划/录取数据。

admission_compare

跨表对比工具。每个 request 指定 name、dataset、filters；公共 group_by 和 metrics 会按各表别名自动映射。

示例：比较南通中学 2025 年和 2024 年录取情况：

{
  "requester_id": "ou_from_event_context",
  "requests": [
    {
      "name": "2025",
      "dataset": "admission_2021_2025",
      "filters": [
        {"field": "year", "op": "eq", "value": 2025},
        {"field": "school", "op": "contains", "value": "南通中学"}
      ]
    },
    {
      "name": "2024",
      "dataset": "admission_2021_2025",
      "filters": [
        {"field": "year", "op": "eq", "value": 2024},
        {"field": "school", "op": "contains", "value": "南通中学"}
      ]
    }
  ],
  "metrics": [
    {"name": "人数", "op": "count"},
    {"name": "最低投档成绩", "op": "min", "field": "score"},
    {"name": "最高投档成绩", "op": "max", "field": "score"},
    {"name": "平均投档成绩", "op": "avg", "field": "score"}
  ]
}

admission_yearly_score_trend

年度分数趋势专用工具。适合“21-26 各年最低分/分数线分别是多少”这类问题；内部最多扫描 21-25 历史表一次、26 录取表一次，避免逐年多次调用。

示例：江苏省 2021-2026 年各年最低投档成绩：

{
  "requester_id": "ou_from_event_context",
  "start_year": 2021,
  "end_year": 2026,
  "province": "江苏"
}

不要自动加 score_gt 或 score_gte；只有用户明确要求排除某类分数时才使用。

admission_permission_check

查看当前请求者自身的身份、显式读写权限和 MCP 运维权限。

admission_update_record

按 record_id 更新单条飞书记录。只有显式配置 write_all: true 的用户可调用，角色名称本身不授予写权限，且只能修改字段白名单中的字段。

4. 常用别名

录取表常用：

• year：录取年份

• province：省市名称

• city：地级市

• school：26 表为匹配中学，21-25 表为中学

• major：录取专业

• major_category：录取大类，仅 26 表有

• subject：科类名称

• score：投档成绩

• rank：省排位

计划表常用：

• year：YEAR 或 Year

• province：SYSSMC

• major：ZSZYMC

• subject：KLMC

• plan_count：PlanNUM

• category：JHLBMC

• direction：ZKFX

• major_group：XBZYDH

5. 验证

不连接飞书时先跑：

python -m unittest discover -s tests -v

部署后建议调用：

{"tool": "admission_config_check", "arguments": {"requester_id": "ou_from_event_context", "ping_feishu": true}}

再用一个人工已知答案的小范围问题核对，例如“2025 年南通中学录取人数”和多维表格界面筛选结果是否一致。

AstrBot 侧还需要启用 plugins/admission_access_control，确保每次招生 MCP 调用的 requester_id 都由飞书事件发送者 ID 强制覆盖。

6. 安全与许可证

仓库只提供代码和脱敏示例配置，不包含真实录取数据。部署前请阅读 SECURITY.md，并始终从可信事件上下文覆盖 requester_id。

本项目采用 MIT License。