local-maps-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 local-maps-mcp contributors
+
+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.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# local-maps-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 用一个小项目，学会开发本地 MCP 服务
+
+一个跑在 macOS 上的本地 MCP 服务。在 AI 工具里配置后说「在地图里搜索西湖景区」，它会打开系统自带的「地图」并搜索这个地点。
+
+源码：<https://github.com/liyufengrex/mcp_search_map>
+
+## MCP 是什么
+
+MCP（Model Context Protocol，模型上下文协议）让 AI 工具调用外部能力。模型负责理解你的话并决定调用哪个工具；MCP 服务把能力登记成工具，执行后把结果交还模型；真正的工作由后面的系统完成，例如打开地图或读取文件。
+
+本地服务由 AI 工具启动，双方用标准输入和标准输出通信，这叫 stdio。日志写到标准错误，标准输出只放协议消息。模型依据工具的名称、说明和参数决定何时调用。
+
+## 本项目做什么
+
+本项目只提供一个工具 `search_map`。参数 `query` 是地点或地址。服务检查参数后，调用 macOS 打开系统地图并发起搜索，然后返回「已向系统地图发送搜索请求：……」。搜索结果以地图窗口为准。不需要地图 API Key。
+
+环境：macOS，Node.js 20 或更高。
+
+## 文件怎么分工
+
+协议入口和地图动作分开：前者向 AI 暴露工具，后者只负责打开地图。
+
+```text
+src/index.js           注册 search_map，用 stdio 等待 AI 工具连接
+src/maps.js            检查参数、生成地图链接、调用 open
+test/maps.test.js      检查链接编码和命令参数
+test/server.test.js    用 MCP 客户端检查工具是否能被调用
+.cursor/mcp.json       一种客户端的配置示例（例如Cursor）
+package.json           依赖、npm start 与 npm test
+```
+
+`src/index.js` 使用官方 SDK `@modelcontextprotocol/server` 创建服务，并用 Zod 描述参数。`src/maps.js` 不处理 MCP 消息。测试用模拟命令代替真正的 `open`，所以 `npm test` 不会反复打开地图。
+
+```bash
+npm install
+npm test
+```
+
+平时由 AI 工具启动。单独执行 `npm start` 时，进程会停住等待连接，用 Ctrl+C 结束。
+
+## 功能怎么实现
+
+1. AI 工具启动 `src/index.js`，`StdioServerTransport` 开始等待调用。
+2. `createServer()` 用 `registerTool()` 登记 `search_map`。`query` 是必填字符串，说明里写了「在地图里搜索地点时使用」。
+3. 调用到达后，处理函数把 `query` 交给 `openMapSearch()`。成功返回搜索已发送；失败返回 `isError: true`，例如空查询、非 macOS，或系统命令失败。
+4. `normalizeQuery()` 去掉首尾空格，空内容会被拒绝。
+5. `buildMapSearchUrl()` 按 Apple [Map Links](https://developer.apple.com/library/archive/featuredarticles/iPhoneURLScheme_Reference/MapLinks/MapLinks.html) 的 `q` 参数生成链接。`q` 就是搜索框里的文字，并用 `encodeURIComponent()` 编码中文、空格和 `&`、`#`：
+
+```text
+https://maps.apple.com/?q=%E8%A5%BF%E6%B9%96%E6%99%AF%E5%8C%BA
+```
+
+`q` 是系统地图长期支持的搜索参数。macOS 15.4 及更高版本还可以使用 [Adopting unified Maps URLs](https://developer.apple.com/documentation/mapkit/unified-map-urls) 里的 `/search?query=`，本项目选择 `q`，使更早的系统也能打开搜索。
+
+6. `openMapSearch()` 用 `execFile()` 执行下面的命令。参数是数组，搜索词只出现在编码后的链接里，最长等待 10 秒：
+
+```text
+/usr/bin/open -b com.apple.Maps <地图链接>
+```
+
+`-b com.apple.Maps` 指定打开系统「地图」。`open` 返回表示系统已经收下请求。
+
+## 在 AI 工具里配置
+
+AI 工具需要一份配置，写明服务名、用来启动的 Node.js，以及入口文件 `src/index.js`。各工具的配置文件位置不同，本地服务通常都使用 `command` 和 `args`。下面以 Cursor 为例。
+
+Cursor 会合并项目级和用户级配置；同名时以项目级为准。市场里的现成 MCP 可以在 **Customize → MCPs** 里点 **Add to Cursor**。本项目是本地服务，使用下面的配置文件。
+
+| 位置 | 文件 | 生效范围 |
+| --- | --- | --- |
+| 项目级 | `.cursor/mcp.json` | 打开本项目时 |
+| 用户级 | `~/.cursor/mcp.json` | 这台电脑上的所有项目 |
+
+本仓库已经写好项目级配置。添加到用户级配置时，保留文件里原有的其他服务。
+
+```json
+{
+  "mcpServers": {
+    "local-maps-mcp": {
+      "command": "node",
+      "args": ["${workspaceFolder}/src/index.js"]
+    }
+  }
+}
+```
+
+`${workspaceFolder}` 是当前项目目录。如果 Cursor 从图形界面启动时找不到 `node`，把 `command` 改成终端里 `nvm which current` 打印出的绝对路径。切换 Node 版本后同步修改，再刷新 MCP。
+
+安装发布后的 npm 包时，入口不再是项目里的源文件：
+
+```json
+{
+  "mcpServers": {
+    "local-maps-mcp": {
+      "command": "npx",
+      "args": ["-y", "local-maps-mcp"]
+    }
+  }
+}
+```
+
+用 Cursor 打开本项目，进入 **Customize → MCPs**。`local-maps-mcp` 已连接时，工具列表里有 `search_map`。改完配置或代码后，在这里刷新该服务。
+
+## 示例：在地图里搜索西湖景区
+
+例如在 Cursor 的 Agent 对话里输入：
+
+```text
+在地图里搜索西湖景区
+```
+
+模型会调用 `search_map`，参数为 `{ "query": "西湖景区" }`。系统地图来到前台并接收这次搜索，对话里出现：
+
+```text
+已向系统地图发送搜索请求：西湖景区
+```

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "local-maps-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "在 macOS 系统地图中搜索地点的本地 MCP 服务",
+  "mcpName": "io.github.liyufengrex/mcp_search_map",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liyufengrex/mcp_search_map.git"
+  },
+  "homepage": "https://github.com/liyufengrex/mcp_search_map#readme",
+  "bugs": {
+    "url": "https://github.com/liyufengrex/mcp_search_map/issues"
+  },
+  "keywords": [
+    "mcp",
+    "macos",
+    "maps"
+  ],
+  "bin": {
+    "local-maps-mcp": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.1",
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.3.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+import { openMapSearch } from "./maps.js";
+
+const instructions = [
+  "这个服务只有 search_map 一个工具。",
+  "用户要求在地图中搜索、查找或打开某个地点时，调用 search_map。",
+  "工具只会打开 macOS 系统地图并发起搜索。",
+  "它不返回地点坐标，也不表示地图已经显示结果。",
+].join("");
+
+/**
+ * 创建 MCP 服务。openSearch 可以在测试里换成不真正打开地图的函数。
+ * @param {{ openSearch?: typeof openMapSearch }} [options]
+ */
+export function createServer({ openSearch = openMapSearch } = {}) {
+  const server = new McpServer(
+    { name: "local-maps-mcp", version: "1.0.0" },
+    { instructions },
+  );
+
+  server.registerTool(
+    "search_map",
+    {
+      title: "在系统地图中搜索",
+      description:
+        "在这台 Mac 的系统地图（Apple 地图）中搜索地点或地址。当用户要求在地图里搜索、查找或打开某个地点时使用。此工具只打开系统地图并发起搜索，不会读取搜索结果，也不能确认地点是否存在或地图是否已经显示完成。",
+      inputSchema: z.object({
+        query: z
+          .string()
+          .describe("要搜索的地点名称或地址，例如“杭州西湖”。去掉首尾空格后不能为空。"),
+      }),
+    },
+    async ({ query }) => {
+      try {
+        const result = await openSearch(query);
+        // 日志只能写 stderr。stdout 是 MCP 协议通道。
+        console.error(`[local-maps-mcp] 已发送搜索请求：${result.query}`);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `已向系统地图发送搜索请求：${result.query}`,
+            },
+          ],
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[local-maps-mcp] 搜索失败：${message}`);
+        return {
+          content: [{ type: "text", text: message }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  return server;
+}
+
+/** 只有直接运行 src/index.js 时才连接 stdio，被测试导入时不启动。 */
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+async function start() {
+  console.error("[local-maps-mcp] 已启动，等待 Cursor 通过 stdio 连接");
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+if (isDirectRun()) {
+  start().catch((error) => {
+    console.error("[local-maps-mcp] 启动失败：", error);
+    process.exitCode = 1;
+  });
+}

package/src/maps.js

@@ -0,0 +1,95 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+
+// promisify 之后可以用 await。execFile 使用参数数组，不会经过 shell。
+const defaultExecFile = promisify(execFileCallback);
+
+/** 系统地图的 bundle id，来自 Maps.app 的 Info.plist。 */
+export const MAPS_BUNDLE_ID = "com.apple.Maps";
+
+/** open 返回前最多等待的时间。open 只负责把请求交给地图，通常很快结束。 */
+export const COMMAND_TIMEOUT_MS = 10_000;
+
+const OPEN_PATH = "/usr/bin/open";
+
+export class MapSearchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MapSearchError";
+  }
+}
+
+/**
+ * 去掉首尾空格，并拒绝空查询。
+ * @param {unknown} query
+ * @returns {string}
+ */
+export function normalizeQuery(query) {
+  if (typeof query !== "string") {
+    throw new MapSearchError("query 必须是字符串");
+  }
+
+  const trimmed = query.trim();
+  if (!trimmed) {
+    throw new MapSearchError("query 不能为空");
+  }
+
+  return trimmed;
+}
+
+/**
+ * 构造系统地图搜索链接。
+ *
+ * Apple《Adopting unified Maps URLs》中的
+ * https://maps.apple.com/search?query= 从 macOS 15.4 开始提供。
+ * 这里使用更早的系统也能识别的 Map Links 格式：
+ * https://maps.apple.com/?q=搜索词
+ * 文档规定 q 是 URL 编码后的搜索文字，地图会把它当作搜索框中的输入。
+ * 官方示例使用 http，这里使用同一主机和同一参数的 https。
+ *
+ * @param {string} query
+ * @returns {string}
+ */
+export function buildMapSearchUrl(query) {
+  const trimmed = normalizeQuery(query);
+  return `https://maps.apple.com/?q=${encodeURIComponent(trimmed)}`;
+}
+
+/**
+ * 校验参数和平台，然后让 macOS 打开系统地图。
+ * options.execFile 供测试替换系统命令，正式运行时不要传入。
+ *
+ * @param {string} query
+ * @param {{
+ *   platform?: NodeJS.Platform,
+ *   execFile?: (file: string, args: string[], options: { timeout: number }) => Promise<unknown>,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {Promise<{ query: string, url: string }>}
+ */
+export async function openMapSearch(query, options = {}) {
+  const trimmed = normalizeQuery(query);
+  const platform = options.platform ?? process.platform;
+
+  if (platform !== "darwin") {
+    throw new MapSearchError("当前系统不是 macOS，无法打开系统地图");
+  }
+
+  const url = buildMapSearchUrl(trimmed);
+  const execFile = options.execFile ?? defaultExecFile;
+  const timeout = options.timeoutMs ?? COMMAND_TIMEOUT_MS;
+
+  try {
+    // man open：-b 用 bundle id 指定由哪个应用打开 URL，从而打开原生地图。
+    await execFile(OPEN_PATH, ["-b", MAPS_BUNDLE_ID, url], { timeout });
+  } catch (error) {
+    if (error && /** @type {{ killed?: boolean }} */ (error).killed) {
+      throw new MapSearchError(`打开系统地图超时（超过 ${timeout} 毫秒）`);
+    }
+
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new MapSearchError(`无法打开系统地图：${detail}`);
+  }
+
+  return { query: trimmed, url };
+}