Epsg Mcp Server

EPSG MCP 服务

日文版 README

一个为全球坐标参考系统（CRS）提供专业知识和决策支持的 MCP 服务。

全球覆盖通过 3 层回退机制实现：

1. 国家数据包（日本、美国州平面坐标系、英国国家格网等），提供专家级建议
2. 没有可用数据包时，自动计算 UTM 分区
3. 最终回退到安全默认值（WGS84 / Web Mercator）

坐标转换由 mcp-server-proj 执行，本服务专注于知识提供和决策支持。

功能

• CRS 搜索：按 EPSG 代码、名称、区域或都道府县搜索 CRS
• 详细信息：获取大地基准、投影方法、适用范围、精度特征等详细信息
• 区域列表：列出日本／全球可用的 CRS，并提供针对不同用途的建议
• CRS 推荐：针对每种用途和地点推荐最优 CRS（支持北海道和冲绳的多分区）
• 用途验证：验证 CRS 选择是否有效，并指出问题和改进建议
• 转换路径规划：使用 BFS 图搜索提出最优转换路径（支持反向转换）
• CRS 比较：从 7 个角度比较 CRS（基准、投影、精度、失真、兼容性等）
• 最佳实践：提供 10 个主题的 CRS 使用指南（测量、Web 地图、数据交换等）
• 故障排查：根据症状诊断 CRS 问题（坐标偏移、计算错误等）
• 国家数据包系统：可扩展的区域专业知识（现有日本、美国、英国数据包；可轻松添加更多）
• 离线运行：本地数据库无需外部 API
• 国际化：工具定义和参数说明采用英文（任何语言的 AI Agent 均可使用）
• 优雅降级：即使没有特定区域的数据包，也可通过 UTM 回退机制在任何地方运行

安装

npm install @shuji-bonji/epsg-mcp

或者直接运行：

npx @shuji-bonji/epsg-mcp

使用方法

Claude Desktop

添加到 claude_desktop_config.json：

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"]
		}
	}
}

启用其他国家数据包

默认情况下仅加载日本数据包。要启用其他数据包（例如美国、英国），请设置 EPSG_PACKS 环境变量：

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"],
			"env": {
				"EPSG_PACKS": "jp,us,uk"
			}
		}
	}
}

可用数据包：jp（日本）、us（美国）、uk/gb（英国）

语言设置

默认输出为英文。要获取日文输出，请设置 EPSG_LANG 环境变量：

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"],
			"env": {
				"EPSG_LANG": "ja"
			}
		}
	}
}

从本地构建版本运行（开发）

要试用尚未发布的构建版本，请将 MCP 客户端指向 build/index.js，而非 npx：

git clone https://github.com/shuji-bonji/epsg-mcp.git
cd epsg-mcp
npm ci
npm run build

{
	"mcpServers": {
		"epsg-dev": {
			"command": "node",
			"args": ["/absolute/path/to/epsg-mcp/build/index.js"],
			"env": {
				"EPSG_PACKS": "jp,us,uk"
			}
		}
	}
}

注意：

• build/index.js 由 npm run build 生成；修改源代码后，请重新构建并重启 MCP 客户端。
• Claude Desktop 等图形界面应用可能无法继承 shell 的 PATH。如果客户端报告 spawn node ENOENT，请将 "node" 替换为 which node 输出的绝对路径。
• 在 Claude Code 中，也可以通过一条命令完成相同的注册：claude mcp add epsg-dev -e EPSG_PACKS=jp,us,uk -- node /absolute/path/to/epsg-mcp/build/index.js
• npx @modelcontextprotocol/inspector node build/index.js 可在 MCP Inspector 中打开本地构建版本。

MCP Inspector

npx @modelcontextprotocol/inspector npx @shuji-bonji/epsg-mcp

工具

search_crs

按关键词搜索 CRS。

// Input
{
  query: string;           // Search keyword (e.g., "JGD2011", "4326", "Tokyo")
  type?: "geographic" | "projected" | "compound" | "vertical" | "engineering";
  region?: "Japan" | "Global";
  limit?: number;          // Default: 10, max: 100
}

// Output
{
  results: CrsInfo[];
  totalCount: number;
}

使用示例：

• “搜索与 JGD2011 相关的 CRS”
• “查找东京可用的投影坐标系”
• “获取 EPSG 代码 6677 的信息”

get_crs_detail

按 EPSG 代码获取 CRS 的详细信息。

// Input
{
  code: string;  // "EPSG:6677" or "6677"
}

// Output
{
  code: string;
  name: string;
  type: CrsType;
  datum?: DatumInfo;
  projection?: ProjectionInfo;
  areaOfUse: AreaOfUse;
  accuracy?: AccuracyInfo;
  remarks?: string;
  useCases?: string[];
  // ...
}

使用示例：

• “告诉我 EPSG:6677 的详细信息”
• “Web Mercator（3857）有什么特点？”

list_crs_by_region

按地区获取可用 CRS 列表和推荐项。

// Input
{
  region: "Japan" | "Global";
  type?: CrsType;
  includeDeprecated?: boolean;  // Default: false
}

// Output
{
  region: string;
  crsList: CrsInfo[];
  recommendedFor: {
    general: string;
    survey: string;
    webMapping: string;
  };
}

使用示例：

• “列出日本可用的 CRS”
• “有哪些全球地理坐标系？”

recommend_crs

根据用途和位置推荐最佳 CRS。

// Input
{
  purpose: "web_mapping" | "distance_calculation" | "area_calculation" |
           "survey" | "navigation" | "data_exchange" | "data_storage" | "visualization";
  location: {
    country?: string;      // "Japan" | "Global"
    region?: string;       // "Kanto", "Hokkaido", "Main Island", "Sakishima", etc.
    prefecture?: string;   // "Tokyo", "Hokkaido", etc.
    city?: string;         // "Sapporo", "Naha", etc. (for multi-zone support)
    boundingBox?: BoundingBox;
    centerPoint?: { lat: number; lng: number };
  };
  requirements?: {
    accuracy?: "high" | "medium" | "low";
    distortionTolerance?: "minimal" | "moderate" | "flexible";
    interoperability?: string[];  // e.g., ["GIS", "CAD", "Web"]
  };
}

// Output
{
  primary: RecommendedCrs;    // Recommended CRS (with score, pros, cons)
  alternatives: RecommendedCrs[];
  reasoning: string;
  warnings?: string[];        // Warnings for areas spanning multiple zones
}

使用示例：

• “东京周边用于距离计算的最佳 CRS 是什么？”
• “在北海道札幌进行测量应该使用什么 CRS？”
• “我想在 Web 应用中显示日本全境地图”

validate_crs_usage

验证指定的 CRS 是否适用于特定用途和位置。

// Input
{
  crs: string;               // "EPSG:3857" or "3857"
  purpose: Purpose;          // Same as recommend_crs
  location: LocationSpec;    // Same as recommend_crs
}

// Output
{
  isValid: boolean;
  score: number;             // Suitability 0-100
  issues: ValidationIssue[]; // List of issues
  suggestions: string[];     // Improvement suggestions
  betterAlternatives?: RecommendedCrs[];  // Alternatives when score is low
}

检测到的问题示例：

• DEPRECATED_CRS：使用了已弃用的 CRS
• AREA_DISTORTION：使用 Web Mercator 进行面积计算
• ZONE_MISMATCH：在东京使用 Zone I（适用于长崎）
• GEOJSON_INCOMPATIBLE：使用投影 CRS 输出 GeoJSON

使用示例：

• “在北海道使用 Web Mercator 进行面积计算可以吗？”
• “在日本使用 EPSG:4326 存储测量数据有什么问题吗？”

suggest_transformation

建议两个 CRS 之间的最佳转换路径。

// Input
{
  sourceCrs: string;    // "EPSG:4301" or "4301"
  targetCrs: string;    // "EPSG:6668" or "6668"
  location?: {
    country?: string;
    prefecture?: string;
    boundingBox?: BoundingBox;
  };
}

// Output
{
  directPath: TransformationPath | null;  // Direct transformation path
  viaPaths: TransformationPath[];         // Indirect transformation paths
  recommended: TransformationPath;        // Recommended path
  warnings: string[];
}

TransformationPath：

• steps：转换步骤数组（from、to、method、accuracy、isReverse）
• totalAccuracy：总体精度
• complexity：复杂度："simple" | "moderate" | "complex"

功能：

• 使用 BFS 图搜索查找最多 4 步的路径
• 自动考虑反向转换（reversible: true）
• 使用已弃用的 CRS（Tokyo Datum、JGD2000）时发出警告
• 对大范围数据转换发出精度警告

使用示例：

• “如何将 Tokyo Datum 转换为 JGD2011？”
• “显示从 WGS84 到 Web Mercator 的转换路径”

compare_crs

从多个角度比较两个 CRS。

// Input
{
  crs1: string;  // "EPSG:4326" or "4326"
  crs2: string;  // "EPSG:6668" or "6668"
  aspects?: ComparisonAspect[];  // Specify comparison aspects (all if omitted)
}

// ComparisonAspect
"datum" | "projection" | "area_of_use" | "accuracy" | "distortion" | "compatibility" | "use_cases"

// Output
{
  comparison: ComparisonResult[];  // Comparison results for each aspect
  summary: string;                 // Summary
  recommendation: string;          // Recommendation
  transformationNote?: string;     // Notes on transformation
}

比较方面：

• datum：基准面比较（例如，WGS84 与 JGD2011 实际上相同）
• projection：投影比较
• area_of_use：使用范围比较
• accuracy：精度特征比较
• distortion：变形特征比较
• compatibility：GIS/Web/CAD/GPS 兼容性比较
• use_cases：用途适用性比较（基于评分）

使用示例：

• “WGS84 和 JGD2011 有什么区别？”
• “比较 Web Mercator 和地理 CRS”
• “从基准面角度比较 JGD2000 和 JGD2011”

get_best_practices

获取使用 CRS 的最佳实践。

// Input
{
  topic: "japan_survey" | "web_mapping" | "data_exchange" | "coordinate_storage" |
         "mobile_gps" | "cross_border" | "historical_data" | "gis_integration" |
         "precision_requirements" | "projection_selection";
  context?: string;  // Additional context (optional, max 500 characters)
}

// Output
{
  topic: string;
  description: string;
  practices: Practice[];       // Recommended practices
  commonMistakes: Mistake[];   // Common mistakes
  relatedTopics: string[];     // Related topics
  references: Reference[];     // Reference materials
}

实践内容：

• title：实践名称
• description：说明
• priority：优先级："must" | "should" | "may"
• rationale：理由
• example?：具体示例

使用示例：

• “在日本进行测量的最佳实践是什么？”
• “创建 Web 地图时如何选择坐标系”
• “使用 GeoJSON 交换数据时需要注意什么”

troubleshoot

排查 CRS 相关问题。

// Input
{
  symptom: string;  // Symptom (2-500 characters)
  context?: {
    sourceCrs?: string;   // Source CRS
    targetCrs?: string;   // Target CRS
    location?: string;    // Target region
    tool?: string;        // Tool being used
    magnitude?: string;   // Magnitude of shift
  };
}

// Output
{
  matchedSymptom: string;         // Matched symptom category
  possibleCauses: Cause[];        // Possible causes (with likelihood)
  diagnosticSteps: DiagnosticStep[]; // Diagnostic steps
  suggestedSolutions: Solution[]; // Solutions
  relatedBestPractices: string[]; // Related best practices
  confidence: "high" | "medium" | "low";  // Diagnosis confidence
}

支持的症状：

• 坐标偏移数百米到数千米（Tokyo Datum 问题等）
• 坐标偏移 1 到数米（转换精度限制等）
• 坐标偏移数厘米到数十厘米（WGS84/JGD2011 差异等）
• 面积/距离计算不正确（Web Mercator 变形等）
• 数据无法显示（CRS 不匹配等）
• 坐标转换错误（未注册参数等）

使用示例：

• “坐标偏差了 400m”
• “面积计算结果不正确”
• “旧数据和新数据无法对齐”

支持的 CRS

日本（JGD2011）

EPSG	名称	用途
6668	JGD2011	地理坐标参考系（参考）
6669-6687	日本平面直角坐标系 I-XIX	测量、大比例尺地图
4612	JGD2000	旧版（已弃用）

美国（NAD83）

EPSG	名称	用途
4269	NAD83	地理坐标参考系（标准）
6318	NAD83(2011)	最新实现
5070	NAD83 / Conus Albers	面积计算
2229	NAD83 / California zone 5	州平面坐标系示例
2263	NAD83 / New York Long Island	州平面坐标系示例

英国（OSGB36/ETRS89）

EPSG	名称	用途
4277	OSGB36	地理坐标参考系（旧版）
4258	ETRS89	地理坐标参考系（现代）
27700	British National Grid	测量、制图
2157	Irish Transverse Mercator	北爱尔兰

全球

EPSG	名称	用途
4326	WGS 84	GPS/GeoJSON 标准
3857	Web Mercator	Web 地图显示
326xx	UTM 分区	距离/面积计算

扩展 CRS 支持（可选）

默认情况下，此服务提供日本和主要全球坐标系的 CRS 数据。若要访问完整的 EPSG 注册表（超过 10,000 个 CRS），可以选择启用 SQLite 支持。

设置

1. 下载 EPSG 数据库

# Using the built-in script
npm run epsg:download-db

# Or specify a custom path
npx tsx scripts/download-epsg-db.ts ./path/to/epsg.db

2. 安装 sql.js（仅当 npm install 未安装时）

sql.js 已列在 optionalDependencies 中，因此运行 npm install @shuji-bonji/epsg-mcp 时通常会自动安装。仅当跳过了此可选依赖（例如使用 --no-optional）时，才需要执行此步骤：

npm install sql.js

3. 配置环境

设置 EPSG_DB_PATH 环境变量：

export EPSG_DB_PATH="/path/to/epsg.db"

或在 Claude Desktop 的 claude_desktop_config.json 中进行配置：

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"],
			"env": {
				"EPSG_DB_PATH": "/path/to/epsg.db"
			}
		}
	}
}

数据来源

EPSG 数据库由 PROJ 提供，该项目再分发 IOGP EPSG Geodetic Parameter Dataset。许可信息请参阅 EPSG 使用条款。

开发

需要 Node.js 22 或更高版本。

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run test:watch

文档

• 使用示例 - 展示 EPSG MCP 如何帮助进行 CRS 选择的实用场景
• 创建国家数据包 - 添加新国家/地区支持的指南

路线图

• 阶段 1 ✅：search_crs、get_crs_detail、list_crs_by_region
• 阶段 2 ✅：recommend_crs、validate_crs_usage
• 阶段 3 ✅：suggest_transformation、compare_crs
• 阶段 4 ✅：get_best_practices、troubleshoot
• 阶段 5 ✅：国际化与多区域支持（国家数据包系统、UTM 回退、可选 SQLite 后端、JP/US/UK 数据包）

相关项目

• mcp-server-proj - 用于执行坐标转换的 MCP 服务
• EPSG.io - EPSG 坐标系数据库

许可证

MIT 许可证 - 详情请参阅 LICENSE。