mcp-server-maptec 1.0.0__tar.gz

mcp_server_maptec-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+.env
+*.log
+.DS_Store
+.cursor/mcp.json
+dist/
+*.egg-info/
+.uv/

mcp_server_maptec-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maptec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_server_maptec-1.0.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.3
+Name: mcp-server-maptec
+Version: 1.0.0
+Summary: MapTech MCP Server (Python) - stdio transport for Cursor / Claude Desktop
+Project-URL: Homepage, https://github.com/maptechbj/maptec-mcp-python
+Project-URL: Repository, https://github.com/maptechbj/maptec-mcp-python
+Author: MapTech
+License: MIT
+Keywords: http,lbs,map,maptec,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.12.0
+Description-Content-Type: text/markdown
+
+# mcp-server-maptec
+
+Maptec的webapi服务已全面兼容[MCP协议](https://modelcontextprotocol.io/docs/getting-started/intro)。
+Maptec MCP Server支持10个LBS服务能力，包含了地点检索、周边检索、输入提示、地点详情、地理编码、逆地理编码、路线规划、距离矩阵、轨迹纠偏、IP定位。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `MAPTEC_API_KEY` | — | **必填**，`mp_1_...` 格式 |
+| `MAPTEC_BASE_URL` | `https://api.maptec.cn` | WebAPI 地址 |
+| `MAPTEC_TIMEOUT_MS` | `30000` | HTTP 超时（毫秒） |
+
+## 快速开始
+
+### 1. 注册账号并申请 AK
+
+前往 **Maptec 开发者中心** 注册账号，创建应用并申请 API Key（AK，`mp_1_...` 格式）。
+
+### 2. 安装 Python 包
+
+推荐使用 [uv](https://docs.astral.sh/uv/) 一键运行（无需预先安装）：
+
+```bash
+uvx mcp-server-maptec
+```
+
+或通过 pip 安装：
+
+```bash
+pip install mcp-server-maptec
+```
+
+安装后可执行：`maptec-mcp-python`
+
+### 3. 在 Cursor 中配置 MCP
+
+以 Cursor 为例，在其 MCP 配置中加入以下内容，填入上一步申请的 API Key 后保存，进入 **Settings → MCP → Reload**：
+
+```json
+{
+  "mcpServers": {
+    "maptec": {
+      "command": "uvx",
+      "args": ["mcp-server-maptec"],
+      "env": {
+        "MAPTEC_API_KEY": "mp_1_YOUR_KEY",
+        "MAPTEC_BASE_URL": "https://api.maptec.cn"
+      }
+    }
+  }
+}
+```
+
+确认 `maptec` 为绿点 Connected，展开可见 10 个 Tool。
+
+上述 `mcpServers` 为 MCP stdio 通用配置，Claude Desktop、Cline、Windsurf 等支持 MCP 的客户端同样适用，差异仅在于配置文件位置与重载方式。
+
+### 4. 应用场景示例：第三方智能体调用 MCP 查询美食
+
+除 Cursor 等 IDE 外，任何支持 MCP 的**第三方智能体**（如基于 LangChain、OpenAI Agents SDK、Claude Agent、或自研 Agent 框架）都可通过官方 MCP 客户端以 stdio 方式拉起本服务，把 10 个 LBS Tool 暴露给大模型自动编排。下面以「查询美食」为例。
+
+**第三方 Agent 接入（stdio 启动 + 传入 API Key）：**
+
+以官方 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 为例，Agent 在初始化时以子进程方式拉起 MCP Server，随后 `list_tools()` 拿到工具清单交给大模型：
+
+```python
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def main():
+    server_params = StdioServerParameters(
+        command="uvx",
+        args=["mcp-server-maptec"],
+        env={
+            "MAPTEC_API_KEY": "mp_1_YOUR_KEY",
+            "MAPTEC_BASE_URL": "https://api.maptec.cn",
+        },
+    )
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            # 交给大模型：把工具清单作为 function/tool 列表
+            tools = await session.list_tools()
+
+            # 大模型决定调用某个工具时：
+            result = await session.call_tool(
+                "map_search_nearby",
+                arguments={
+                    "query": "火锅",
+                    "locationLimit": {
+                        "center": {"latitude": 1.3048, "longitude": 103.8318},
+                        "radius": 2000,
+                    },
+                    "resultLimit": 5,
+                    "region": "SG",
+                },
+            )
+            print(result)
+
+asyncio.run(main())
+```
+
+> Node.js 智能体同理：用 `@modelcontextprotocol/sdk` 的 `StdioClientTransport`，`command`/`args`/`env` 改为 `npx -y @maptec/mcp-server-node` 即可。
+
+**用户提问（发给第三方智能体）：**
+
+> 我在新加坡乌节路附近，想找评分高的火锅店，推荐几家，并告诉我从这里去最近一家怎么走。
+
+**Agent 编排流程：**
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant LLM as 智能体大模型
+    participant MCP as Maptec MCP
+    U->>LLM: 找乌节路附近评分高的火锅店并给出路线
+    LLM->>MCP: map_search_geocode(乌节路)
+    MCP-->>LLM: 坐标
+    LLM->>MCP: map_search_nearby(火锅, center, resultLimit)
+    MCP-->>LLM: POI 列表(placeId...)
+    LLM->>MCP: map_search_places(placeId)
+    MCP-->>LLM: 店铺详情
+    LLM->>MCP: map_routes_directions(origin, destination, walking)
+    MCP-->>LLM: 步行路线
+    LLM-->>U: 自然语言推荐 + 导航
+```
+
+**关键工具调用示例：**
+
+1. `map_search_geocode` 把地址转为坐标：
+
+```json
+{
+  "address": "乌节路, 新加坡",
+  "region": "SG"
+}
+```
+
+2. `map_search_nearby` 以坐标为中心检索周边火锅店：
+
+```json
+{
+  "query": "火锅",
+  "locationLimit": {
+    "center": { "latitude": 1.3048, "longitude": 103.8318 },
+    "radius": 2000
+  },
+  "resultLimit": 5,
+  "region": "SG"
+}
+```
+
+3. `map_search_places` 取 Top 店铺详情，`placeId` 来自上一步结果：
+
+```json
+{
+  "placeId": "PLACE_ID_FROM_NEARBY",
+  "language": "zh-CN",
+  "region": "SG"
+}
+```
+
+4. `map_routes_directions` 规划到最近一家的步行路线：
+
+```json
+{
+  "origin": { "latitude": 1.3048, "longitude": 103.8318 },
+  "destination": { "latitude": 1.3021, "longitude": 103.8360 },
+  "mode": "walking"
+}
+```
+
+**Agent 最终回答示例：**
+
+> 已为你找到乌节路附近 3 家评分较高的火锅店：
+> 1. 海底捞火锅（ION Orchard）— 评分 4.6，营业至 22:30，步行约 6 分钟；
+> 2. 小龙坎老火锅（313@Somerset）— 评分 4.5，营业至 23:00，步行约 9 分钟；
+> 3. 谭鸭血老火锅（Orchard Central）— 评分 4.4，营业至 22:00，步行约 11 分钟。
+>
+> 最近的是海底捞（ION Orchard），从你当前位置沿乌节路向东步行约 450 米、6 分钟即可到达。
+
+以上全部由大模型自动调用 MCP 工具完成，用户无需关心任何接口参数。
+
+## Tool 列表
+
+| Tool | 说明 |
+|------|------|
+| `map_search_text` | 关键字检索 |
+| `map_search_nearby` | 周边检索 |
+| `map_search_suggest` | 输入提示 |
+| `map_search_places` | 地点详情 |
+| `map_search_geocode` | 地理编码 |
+| `map_search_reverse` | 逆地理编码 |
+| `map_routes_directions` | 路线规划 |
+| `map_matrix_distance` | 距离矩阵 |
+| `map_track_snap_to_roads` | 轨迹纠偏 |
+| `map_location_ip` | IP 定位 |
+
+## License
+
+[MIT](./LICENSE) © 2026 Maptec

mcp_server_maptec-1.0.0/README.md

@@ -0,0 +1,204 @@
+# mcp-server-maptec
+
+Maptec的webapi服务已全面兼容[MCP协议](https://modelcontextprotocol.io/docs/getting-started/intro)。
+Maptec MCP Server支持10个LBS服务能力，包含了地点检索、周边检索、输入提示、地点详情、地理编码、逆地理编码、路线规划、距离矩阵、轨迹纠偏、IP定位。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `MAPTEC_API_KEY` | — | **必填**，`mp_1_...` 格式 |
+| `MAPTEC_BASE_URL` | `https://api.maptec.cn` | WebAPI 地址 |
+| `MAPTEC_TIMEOUT_MS` | `30000` | HTTP 超时（毫秒） |
+
+## 快速开始
+
+### 1. 注册账号并申请 AK
+
+前往 **Maptec 开发者中心** 注册账号，创建应用并申请 API Key（AK，`mp_1_...` 格式）。
+
+### 2. 安装 Python 包
+
+推荐使用 [uv](https://docs.astral.sh/uv/) 一键运行（无需预先安装）：
+
+```bash
+uvx mcp-server-maptec
+```
+
+或通过 pip 安装：
+
+```bash
+pip install mcp-server-maptec
+```
+
+安装后可执行：`maptec-mcp-python`
+
+### 3. 在 Cursor 中配置 MCP
+
+以 Cursor 为例，在其 MCP 配置中加入以下内容，填入上一步申请的 API Key 后保存，进入 **Settings → MCP → Reload**：
+
+```json
+{
+  "mcpServers": {
+    "maptec": {
+      "command": "uvx",
+      "args": ["mcp-server-maptec"],
+      "env": {
+        "MAPTEC_API_KEY": "mp_1_YOUR_KEY",
+        "MAPTEC_BASE_URL": "https://api.maptec.cn"
+      }
+    }
+  }
+}
+```
+
+确认 `maptec` 为绿点 Connected，展开可见 10 个 Tool。
+
+上述 `mcpServers` 为 MCP stdio 通用配置，Claude Desktop、Cline、Windsurf 等支持 MCP 的客户端同样适用，差异仅在于配置文件位置与重载方式。
+
+### 4. 应用场景示例：第三方智能体调用 MCP 查询美食
+
+除 Cursor 等 IDE 外，任何支持 MCP 的**第三方智能体**（如基于 LangChain、OpenAI Agents SDK、Claude Agent、或自研 Agent 框架）都可通过官方 MCP 客户端以 stdio 方式拉起本服务，把 10 个 LBS Tool 暴露给大模型自动编排。下面以「查询美食」为例。
+
+**第三方 Agent 接入（stdio 启动 + 传入 API Key）：**
+
+以官方 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 为例，Agent 在初始化时以子进程方式拉起 MCP Server，随后 `list_tools()` 拿到工具清单交给大模型：
+
+```python
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def main():
+    server_params = StdioServerParameters(
+        command="uvx",
+        args=["mcp-server-maptec"],
+        env={
+            "MAPTEC_API_KEY": "mp_1_YOUR_KEY",
+            "MAPTEC_BASE_URL": "https://api.maptec.cn",
+        },
+    )
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            # 交给大模型：把工具清单作为 function/tool 列表
+            tools = await session.list_tools()
+
+            # 大模型决定调用某个工具时：
+            result = await session.call_tool(
+                "map_search_nearby",
+                arguments={
+                    "query": "火锅",
+                    "locationLimit": {
+                        "center": {"latitude": 1.3048, "longitude": 103.8318},
+                        "radius": 2000,
+                    },
+                    "resultLimit": 5,
+                    "region": "SG",
+                },
+            )
+            print(result)
+
+asyncio.run(main())
+```
+
+> Node.js 智能体同理：用 `@modelcontextprotocol/sdk` 的 `StdioClientTransport`，`command`/`args`/`env` 改为 `npx -y @maptec/mcp-server-node` 即可。
+
+**用户提问（发给第三方智能体）：**
+
+> 我在新加坡乌节路附近，想找评分高的火锅店，推荐几家，并告诉我从这里去最近一家怎么走。
+
+**Agent 编排流程：**
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant LLM as 智能体大模型
+    participant MCP as Maptec MCP
+    U->>LLM: 找乌节路附近评分高的火锅店并给出路线
+    LLM->>MCP: map_search_geocode(乌节路)
+    MCP-->>LLM: 坐标
+    LLM->>MCP: map_search_nearby(火锅, center, resultLimit)
+    MCP-->>LLM: POI 列表(placeId...)
+    LLM->>MCP: map_search_places(placeId)
+    MCP-->>LLM: 店铺详情
+    LLM->>MCP: map_routes_directions(origin, destination, walking)
+    MCP-->>LLM: 步行路线
+    LLM-->>U: 自然语言推荐 + 导航
+```
+
+**关键工具调用示例：**
+
+1. `map_search_geocode` 把地址转为坐标：
+
+```json
+{
+  "address": "乌节路, 新加坡",
+  "region": "SG"
+}
+```
+
+2. `map_search_nearby` 以坐标为中心检索周边火锅店：
+
+```json
+{
+  "query": "火锅",
+  "locationLimit": {
+    "center": { "latitude": 1.3048, "longitude": 103.8318 },
+    "radius": 2000
+  },
+  "resultLimit": 5,
+  "region": "SG"
+}
+```
+
+3. `map_search_places` 取 Top 店铺详情，`placeId` 来自上一步结果：
+
+```json
+{
+  "placeId": "PLACE_ID_FROM_NEARBY",
+  "language": "zh-CN",
+  "region": "SG"
+}
+```
+
+4. `map_routes_directions` 规划到最近一家的步行路线：
+
+```json
+{
+  "origin": { "latitude": 1.3048, "longitude": 103.8318 },
+  "destination": { "latitude": 1.3021, "longitude": 103.8360 },
+  "mode": "walking"
+}
+```
+
+**Agent 最终回答示例：**
+
+> 已为你找到乌节路附近 3 家评分较高的火锅店：
+> 1. 海底捞火锅（ION Orchard）— 评分 4.6，营业至 22:30，步行约 6 分钟；
+> 2. 小龙坎老火锅（313@Somerset）— 评分 4.5，营业至 23:00，步行约 9 分钟；
+> 3. 谭鸭血老火锅（Orchard Central）— 评分 4.4，营业至 22:00，步行约 11 分钟。
+>
+> 最近的是海底捞（ION Orchard），从你当前位置沿乌节路向东步行约 450 米、6 分钟即可到达。
+
+以上全部由大模型自动调用 MCP 工具完成，用户无需关心任何接口参数。
+
+## Tool 列表
+
+| Tool | 说明 |
+|------|------|
+| `map_search_text` | 关键字检索 |
+| `map_search_nearby` | 周边检索 |
+| `map_search_suggest` | 输入提示 |
+| `map_search_places` | 地点详情 |
+| `map_search_geocode` | 地理编码 |
+| `map_search_reverse` | 逆地理编码 |
+| `map_routes_directions` | 路线规划 |
+| `map_matrix_distance` | 距离矩阵 |
+| `map_track_snap_to_roads` | 轨迹纠偏 |
+| `map_location_ip` | IP 定位 |
+
+## License
+
+[MIT](./LICENSE) © 2026 Maptec

mcp_server_maptec-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "mcp-server-maptec"
+version = "1.0.0"
+description = "MapTech MCP Server (Python) - stdio transport for Cursor / Claude Desktop"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "MapTech" }]
+keywords = ["http", "mcp", "map", "maptec", "lbs"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp[cli]>=1.12.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/maptechbj/maptec-mcp-python"
+Repository = "https://github.com/maptechbj/maptec-mcp-python"
+
+[project.scripts]
+maptec-mcp-python = "maptec_mcp_python:main"
+
+[build-system]
+requires = ["hatchling>=1.21,<1.27"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["twine>=6.0.0", "build>=1.2.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maptec_mcp_python"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/maptec_mcp_python/schemas/tools.json" = "maptec_mcp_python/schemas/tools.json"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/maptec_mcp_python", "schemas", "scripts", "README.md"]