Metadata-Version: 2.3
Name: mcp-server-maptec
Version: 1.0.1
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
```

安装后可执行：`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@1.0.1"],
      "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@1.0.1"],
        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
