LLM: "苏州与上海不相邻"
  → check_adjacency("320500", "310000")
  ← { valid: false, correction: "苏州市 与 上海市 相邻，共享边界 42.3km",
       evidence: { shared_boundary_length_km: 42.3 } }
LLM: "我修正之前的说法，苏州与上海实际上是相邻的……"

LLM Client ──MCP Protocol──► GeoOntology-MCP (TypeScript)
                                    │
                          ┌─────────┴─────────┐
                          │  Ontology Engine    │
                          │  - 层级遍历 (KG)    │
                          │  - 拓扑查询 (PostGIS)│
                          │  - 约束校验 (两层)  │
                          │  - 空间运算 (PostGIS)│
                          │  - 路径搜索 (BFS)   │
                          └─────────┬─────────┘
                                    │
                      ┌─────────────┴─────────────┐
                      │                           │
              Knowledge Graph (内存)        PostGIS (持久化)
              - 46,413 节点               - boundary geometries
              - 44,956 BELONGS_TO 边      - admin_adjacency (预计算)
              - 地名/拼音/英文索引         - admin_containment (预计算)
                                          - admin_attributes (属性数据)

{
  "valid": true,
  "claim": "南京市 属于 江苏省",
  "explanation": "层级关系确认: 南京市(city) → 江苏省(province)"
}

{
  "valid": false,
  "claim": "南京市 属于 浙江省",
  "explanation": "南京市 不属于 浙江省，实际属于 江苏省(province)",
  "correction": "实际归属: 南京市 属于 江苏省(province)",
  "evidence": {
    "actual_parent_id": "320000",
    "actual_parent_name": "江苏省",
    "actual_parent_level": "province"
  }
}

谜题: "我是江苏省面积最小的与安徽接壤的地级市"
→ get_children("320000")        → 获取江苏所有地级市
→ describe_region(每个市)        → 获取面积
→ check_adjacency(每个市, "340000") → 筛选与安徽相邻的
→ 综合约束得出答案: 南京市

# 安装依赖
npm install

# 首次运行：预计算邻接表（约 30 秒）
npm run materialize

# 导入属性数据（人口/GDP/面积）
npx tsx scripts/materialize-attributes.ts

# 启动 MCP 服务器
npm run dev

Loading knowledge graph...
Loaded 46413 nodes, 44956 edges
Connecting to PostGIS...
PostGIS connected
Registered 2 mapping resources
GeoOntology-MCP server running

{
  "mcpServers": {
    "geo-ontology": {
      "command": "npx",
      "args": ["tsx", "/path/to/GeoOntology-MCP/src/index.ts"],
      "env": {
        "KG_PATH": "/path/to/admin_knowledge_graph.json",
        "PGHOST": "127.0.0.1",
        "PGPORT": "5432",
        "PGDATABASE": "your_database",
        "PGUSER": "your_user",
        "PGPASSWORD": "your_password"
      }
    }
  }
}

→ resolve_place(name="南京")
← [{ id: "320100", name: "南京市", level: "city", parentName: "江苏省", score: 104 }]

→ get_ancestors(id="320100")
← [{ id: "320000", name: "江苏省", level: "province", type: "省" }]

→ check_containment(child_id="320102", parent_id="320000")
← { valid: true, claim: "玄武区 属于 江苏省",
     explanation: "层级关系确认: 玄武区(county) → 南京市(city) → 江苏省(province)" }

→ resolve_place(name="Nanjing")
← [{ id: "320100", name: "南京市", level: "city", score: 90 }]

→ resolve_place(name="jss")
← [{ id: "320000", name: "江苏省", level: "province", score: 40 }]

→ find_path(id_a="320000", id_b="330000")
← { found: true, path: ["320000", "330000"], pathNames: ["江苏省", "浙江省"],
     hops: 1, totalBoundaryKm: 152.7 }

→ measure_distance(id_a="320100", id_b="330100")
← { idA: "320100", nameA: "南京市", idB: "330100", nameB: "杭州市",
     distanceKm: 267.4, method: "centroid-to-centroid" }

→ find_within(id="320100", radius_km=200)
← [{ id: "330100", name: "杭州市", distanceKm: 267.4, ... }, ...]

→ compare_regions(ids=["110000", "310000", "320000"], metric="population")
← { metric: "population", regions: [
     { id: "320000", name: "江苏省", value: 85054000, rank: 1 },
     { id: "110000", name: "北京市", value: 21893095, rank: 2 },
     { id: "310000", name: "上海市", value: 24870895, rank: 3 }
   ] }

→ describe_region(id="110000", include_geometry=true, geometry_tolerance_km=0.5)
← { id: "110000", name: "北京市", ..., geometry: { type: "Polygon", coordinates: [...] },
     geometryToleranceKm: 0.5 }

src/
  index.ts                        # MCP 服务器入口
  data-source/
    interface.ts                  # GeoDataSource 接口 + 所有类型定义
    postgis-adapter.ts            # PostGIS 实现（核心适配器）
    column-map.ts                 # 表名/列名映射 + inferLevel()
  knowledge-graph/
    types.ts                      # KG 节点/边类型（含拼音/别名字段）
    loader.ts                     # KG JSON 加载 + 拼音索引 + 别名合并
    english-aliases.ts            # 省市英文名映射 (~60个)
  ontology/
    hierarchy.ts                  # 层级遍历（getAncestors, getChildren）
    resolver.ts                   # 地名消歧（中文/拼音/英文四级匹配）
    verifier.ts                   # 包含关系校验（KG 层级检查）
    pathfinder.ts                 # BFS 路径搜索（纯函数）
  tools/
    registration.ts               # 10 个工具注册到 McpServer
  resources/
    registration.ts               # MCP Resource 注册（mapping_knowledge）
scripts/
  materialize-adjacency.ts        # 邻接预计算脚本
  materialize-attributes.ts       # 属性数据导入脚本
skills/
  geo-riddle/SKILL.md             # GeoRiddle 谜题推理 skill
  geo-fact-check/SKILL.md         # GeoFactCheck 断言校验 skill
mapping_knowledge/
  mapping_resources/              # MCP Resource JSON 文件
    projection-advice.json        # 投影选择指南
    admin-level-guide.json        # 行政区划编码规则
data/
  admin-attributes.csv            # 省级属性数据（人口/GDP/面积）
tests/
  knowledge-graph.test.ts         # KG 加载器测试
  hierarchy.test.ts               # 层级遍历测试
  resolver.test.ts                # 地名消歧测试
  verifier.test.ts                # 校验逻辑测试
  column-map.test.ts              # 列映射测试
  pinyin-resolver.test.ts         # 拼音消歧测试
  path.test.ts                    # BFS 路径搜索测试
  fixtures/
    sample-kg.json                # 测试用样本 KG

interface GeoDataSource {
  connect(): Promise<void>;
  close(): Promise<void>;
  getRegionInfo(id: string): Promise<RegionInfo | null>;
  getAncestors(id: string): Promise<HierarchyNode[]>;
  getChildren(id: string): Promise<HierarchyNode[]>;
  getNeighbors(id: string): Promise<AdjacencyResult[]>;
  checkContainment(childId: string, parentId: string): Promise<VerificationResult>;
  checkAdjacency(idA: string, idB: string): Promise<VerificationResult>;
  resolvePlace(name: string, context?: string): Promise<PlaceCandidate[]>;
  findPath(idA: string, idB: string, maxHops?: number): Promise<PathResult>;
  getRegionGeometry(id: string, toleranceKm?: number): Promise<RegionGeometry | null>;
  measureDistance(idA: string, idB: string): Promise<DistanceResult | null>;
  findWithin(id: string, radiusKm: number): Promise<WithinResult[]>;
  getAttributes(id: string): Promise<RegionAttributes | null>;
  compareRegions(ids: string[], metric: 'population' | 'gdp' | 'areaSqKm'): Promise<CompareResult>;
}

npm test