古籍空间可视化 MCP Server

dhcckb-ancient-map 是一个 stdio 模式的 MCP Server（Python ≥ 3.10，仅依赖 mcp>=0.9.0），接收古籍文本的结构化抽取结果（地点、空间关系、人物轨迹），通过三级级联地名解析自动补全坐标，生成自包含的交互式 HTML 可视化地图。

支持 Cherry Studio、Claude Desktop 等 MCP 客户端导入使用。

功能概览

安装

uvx dhcckb-ancient-map

或在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "dhcckb-ancient-map": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dhcckb-ancient-map"]
    }
  }
}

输入数据格式

{
  "locations": [
    {
      "id": "loc1",
      "name": "长安",
      "type": "concrete",
      "coordinates": [108.94, 34.26],
      "year": -208,
      "description": "西汉都城"
    },
    {
      "id": "loc2",
      "name": "洛阳",
      "type": "concrete",
      "year": 200,
      "description": "东汉都城"
    }
  ],
  "relations": [
    {
      "from": "loc1",
      "to": "loc2",
      "type": "path",
      "trigger": "自长安至洛阳",
      "description": "东西交通"
    }
  ],
  "agents": [
    {
      "name": "司马迁",
      "color": "#d63031",
      "trajectory": ["loc1", "loc2"]
    }
  ],
  "natural_features": [
    {
      "feature_type": "mountain",
      "coordinates": [110.08, 34.49],
      "hint": "华山"
    }
  ],
  "mode": "auto",
  "title": "《史记》空间关系图",
  "source_text": "太史公自叙……"
}

字段说明

• locations: type 为 concrete 时 coordinates 可选（不提供则自动调用 API 查询），abstract 时无坐标仅有拓扑关系。
• relations: from/to 引用 locations 的 id，type 支持 path/contain/direction/adjacent/distance。
• agents: trajectory 是 locations.id 的有序序列。
• natural_features: 山脉、河流、森林等自然地理要素，作为背景装饰层渲染。
• mode: auto（自动选择）/ gis（GIS 地图）/ topo（拓扑图）/ mixed（混合叠加）。

三级级联地名解析

1. 内置坐标表（data/ancient_places.json，63 个核心地名，人工校验）—— 命中则跳过 API
2. CHGIS TGAZ API（http://tgaz.fudan.edu.cn/tgaz/placename，免认证，覆盖前 222 年~1911 年）—— 带 yr 年份过滤
3. GeoNames API（http://api.geonames.org/searchJSON）—— 中文地名自动转拼音搜索，补充山川河流

渲染特性

• 三段式页面布局：原典文本区 → 地名列表区 → 交互式地图区
• 古风配色：宣纸暖色背景（#f5f0e8）、传统色系标注
• 标签防重叠：8 个候选方向碰撞检测，选冲突最少方向放置，偏移时画引线
• SVG 缩放平移：鼠标滚轮以光标为中心缩放、拖拽平移、双击重置
• 自然地理装饰：山脉（山形 SVG path）、河流（波浪线）、森林（树形符号），opacity=0.5 在关系线/轨迹下层渲染
• 动态缩放策略：坐标范围小时按比例加 padding（range×0.5），范围大时加固定 padding
• 力导向布局：存在 abstract 地点时自动切换拓扑图（纯 JS 实现，无 D3.js 依赖）
• 自包含 HTML：所有 CSS/JS 内嵌，无外部 CDN 依赖，离线可用，适合长期存档

已知限制

CHGIS API

• 城市内部小地名不准：坊、里、曲、巷等小地名 API 解析普遍不准（实测《李娃传》长安坊名全部错误），需手动赋坐标。
• 朝代歧义：同名地名存在朝代歧义，必须传 yr 参数做时间过滤。
• 山川类地名支持有限：自然地名（山、河、湖）CHGIS 覆盖不完整，需用 GeoNames 补充。

GeoNames API

• 拼音匹配不精确：依赖中文→拼音转换，部分地名匹配不精确，可能返回错误结果。
• 古代地名覆盖不足：GeoNames 主要收录现代地名，古代地名查询效果有限。

坐标解析

• 三级级联均无法解析的地名，坐标将设为 [0, 0]，需手动补充。
• 建议优先在 data/ancient_places.json 中补充常用地名坐标。

项目结构

dhcckb-ancient-map/
├── src/dhcckb_ancient_map/
│   ├── __init__.py
│   ├── server.py          # MCP Server 入口，注册 3 个 Tool
│   ├── extractor.py       # 数据验证与增强
│   ├── geo_resolver.py    # 三级级联地名解析
│   └── renderer.py        # HTML 渲染引擎
├── data/
│   └── ancient_places.json # 63 个核心地名坐标表
├── pyproject.toml
└── README.md

许可

MIT License