YouMap MCP服务器

YouMap API的模型上下文协议（MCP）服务器，使人工智能助手能够通过自然语言交互创建和管理地图。

安装

全局安装（推荐）

npm install -g @youmap/youmap-mcp

本地安装

npm install @youmap/youmap-mcp

用法

使用克劳德桌面

将此添加到您的Claude Desktop配置文件中：

macOS: ~/.config/claude-desktop/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

使用API密钥（推荐）

{
  "mcpServers": {
    "youmap": {
      "command": "youmap-mcp",
      "env": {
        "YOUMAP_API_KEY": "ym_your_api_key_here",
        "YOUMAP_BASE_URL": "https://developer.youmap.com",
        "SERP_API_KEY": "",
        "BFL_API_KEY": "",
        "UNSPLASH_ACCESS_KEY": ""
      }
    }
  }
}

使用OAuth凭据（传统）

{
  "mcpServers": {
    "youmap": {
      "command": "youmap-mcp",
      "env": {
        "YOUMAP_CLIENT_ID": "your_client_id_here",
        "YOUMAP_CLIENT_SECRET": "your_client_secret_here",
        "YOUMAP_BASE_URL": "https://developer.youmap.com",
        "SERP_API_KEY": "",
        "BFL_API_KEY": "",
        "UNSPLASH_ACCESS_KEY": ""
      }
    }
  }
}

环境变量

身份验证（选择一个）

YOUMAP_API_KEY：YouMap API密钥（推荐-更简单的设置）
YOUMAP_CLIENT_ID + YOUMAP_CLIENT_SECRET：OAuth客户端凭据（旧版）

配置

YOUMAP_BASE_URL：YouMap API的基本URL（默认为 https://developer.youmap.com)

可选-图像API

SERP_API_KEY：SERP API获取帖子图像的关键（search_image操作）
BFL_API_KEY：BFL使用FLUX-PRO-1.1模型生成地图图像的关键（generate_image动作）
UNSPLASH_ACCESS_KEY：作为SERP回退的Unsplash密钥（search_image操作）

认证

API密钥验证（推荐）

最简单的身份验证方法是使用API密钥：

在以下网址创建YouMap帐户 youmap.com
在生成API密钥 docs.youmap.com
设置 YOUMAP_API_KEY 环境变量

API密钥通过 X-API-Key 每个请求的标题。

OAuth 2.0身份验证（传统）

或者，您可以使用OAuth 2.0客户端凭据流：

从YouMap的开发者门户获取客户端凭据
设置两者 YOUMAP_CLIENT_ID 和 YOUMAP_CLIENT_SECRET 环境变量

服务器自动执行以下操作：

使用您的客户端ID和密钥进行身份验证以获取访问令牌
令牌过期时自动管理令牌刷新
在需要时使用新令牌重试失败的请求

HTTP服务器模式

MCP服务器还可以作为HTTP服务器运行，以便与其他工具集成：

MCP_MODE=http PORT=3000 youmap-mcp

端点

端点	方法	描述
`/health`	GET	健康检查
`/tools`	GET	列出可用工具
`/v1/mcp`	POST	JSON-RPC MCP端点（API密钥身份验证）
`/:clientId/:clientSecret/v1/mcp`	POST	JSON-RPC MCP端点（OAuth）

API密钥验证

curl -X POST http://localhost:3000/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ym_your_api_key_here" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

OAuth身份验证

curl -X POST http://localhost:3000/{clientId}/{clientSecret}/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

可用工具

`create_map`

创建一个新的地图，用于按地理位置组织帖子、地点和内容。

参数：

name （必填）：地图名称（3-50个字符）
description （可选）：地图描述（5-500个字符）
accessLevel （可选）：访问级别- "public", "inviteOnly"，或 "private" （默认值： "public")
coverImageFromUrl （可选）：封面图片URL
invitedUserIds （可选）：要邀请的用户ID数组（用于 inviteOnly 地图）
categoryIds （可选）：类别ID数组（1-3个类别，默认值： [13])
readonly （可选）：布尔值，用于防止其他人发布（默认值： false)
boundingBox （可选）：对象 north, south, east, west 坐标

克劳德用法示例：

"Create a public map called 'Coffee Shops in NYC' with description 'Best coffee spots in New York City' and set it to readonly"

`create_post`

在特定地理位置的地图上创建新帖子。

参数：

mapId （必填）：创建帖子的地图的ID
latitude （必填）：纬度坐标（-90到90）
longitude （必填）：经度坐标（-180至180）
actionId （必填）：用于此帖子的操作/模板的ID
name （可选）：帖子名称/标题（最多100个字符）
description （可选）：帖子的描述或内容（最多500个字符）
address （可选）：位置的街道地址
placeId （可选）：地图服务中的地点ID
imageIds （可选）：要附加到帖子的图像ID数组
saveAsTemplate （可选）：另存为模板以备将来使用（默认值：false）
contentOrigin （可选）：内容来源-“应用程序”或“公共API”（默认：“公共API“）
fields （可选）：基于操作模板的自定义字段值

克劳德用法示例：

"Create a post on map 123 at coordinates 40.7128, -74.0060 with action 456 titled 'Great Coffee Shop' and description 'Amazing espresso and friendly staff'"

`create_action`

创建一个新的操作（帖子模板），定义帖子的结构。动作可以作为帖子可以包含哪些字段和内容类型的蓝图。

参数：

name （必填）：动作/帖子模板的名称（3-50个字符）
mapId （必填）：此操作所属地图的ID
emoji （可选）：表示操作的表情符号（默认值：'：speech_balloon:'）
borderColor （可选）：动作边框的十六进制颜色（例如，“#FF5733”）
duration （可选）：帖子保持活动状态的时间-“永远”、“1_hour”、“6_hours”、“12-hours”、“1day”、“3_days”、“1Tweek”、“1Mmonth”（默认值：“永远”）
order （可选）：显示其他操作的顺序
fields （可选）：使用textFields、mediaFields、websiteFields、ratingFields、dateField定义字段结构

克劳德用法示例：

"Create an action on map 123 called 'Restaurant Review' with a food emoji and rating field"
"Make a post template for map 456 named 'Event Listing' with text fields for description and date field"

`list_actions`

从定义可用帖子结构的特定映射中检索操作（帖子模板）。

参数：

mapId （必填）：从中检索操作的地图的ID
limit （可选）：要返回的最大操作数（1-100，默认值：20）
offset （可选）：分页时要跳过的操作数（默认值：0）
orderBy （可选）：按“id”、“name”、“表情符号”、“created_at”、“updated_at”和“Order”排序（默认：“Order”）
sort （可选）：排序方向“asc”或“desc”（默认：“asc“）
enabledOnly （可选）：仅返回已启用的操作（默认值：true）
phrase （可选）：按名称筛选的搜索短语

克劳德用法示例：

"Show me all actions available on map 123"
"List the post templates for map 456 ordered by name"
"Find actions on map 789 containing the word 'review'"

`list_posts`

通过分页和过滤支持从特定地图中检索帖子列表。

参数：

mapId （必填）：用于检索帖子的地图ID
limit （可选）：返回的最大帖子数（1-100，默认值：20）
offset （可选）：分页时要跳过的帖子数（默认值：0）
orderBy （可选）：如何对结果进行排序-“趋势”、“最新”、“旧”、“距离”（默认值：“趋势”）
centerLatitude （可选）：基于距离排序的纬度（如果orderBy是“距离”，则需要）
centerLongitude （可选）：基于距离排序的经度（如果orderBy是“距离”，则需要）
filterActionIds （可选）：按特定操作ID筛选帖子

克劳德用法示例：

"Show me all posts on map 123"
"List the newest 10 posts from map 456"
"Show me posts on map 789 ordered by distance from coordinates 40.7128, -74.0060"
"Get posts from map 123 filtered by action IDs 10, 20, 30"

`list_maps`

使用分页支持检索属于经过身份验证的用户的地图列表。

参数：

limit （可选）：要返回的最大映射数（1-100，默认值：20）
offset （可选）：分页时要跳过的映射数（默认值：0）

克劳德用法示例：

"Show me all my maps"
"List my first 10 maps"
"Show me maps 21-40" (offset: 20, limit: 20)

`update_action`

更新现有操作（发布模板）。您应该始终更新操作的最新/最新版本。

参数：

actionId （必填）：要更新的操作的ID
version （必填）：要更新的版本号（应为最新版本）
name （可选）：动作/帖子模板的新名称（3-50个字符）
emoji （可选）：表示此操作的新表情符号
borderColor （可选）：动作边框的新十六进制颜色（例如，“#FF5733”）
duration （可选）：帖子保持活跃的时间-“永远”、“BasedOnDateField”、“两分钟”、“半小时”、“一小时”、《四小时》、《一天》、《两天》、“三天”、“七天”
autoPublish （可选）：是否自动发布更新版本（默认：false）
fields （必填）：更新了通过此行动创建的职位的结构和字段

克劳德用法示例：

"Update action 123 version 2 to change the name to 'Coffee Shop Reviews' and add a rating field"
"Modify action 456 to include media fields and change the border color to red"

`update_post`

更新现有帖子。您可以修改帖子的内容、位置、字段和其他属性。

参数：

postId （必填）：要更新的帖子ID
name （可选）：帖子的新名称/标题（最多100个字符）
description （可选）：帖子的新描述或内容（最多500个字符）
latitude （可选）：新纬度坐标（-90到90）
longitude （可选）：新的经度坐标（-180到180）
actionId （可选）：用于此帖子的新操作/模板ID
address （可选）：位置的新地址
placeId （可选）：来自地图服务的新地点ID
deletedImageIds （可选）：要从帖子中删除的图像ID数组
createdFields （可选）：要添加到帖子中的新字段
updatedFields （可选）：要更新的现有字段
deletedFields （可选）：要从帖子中删除的字段ID数组

克劳德用法示例：

"Update post 789 to change the title to 'Amazing Coffee' and move it to coordinates 40.7589, -73.9851"
"Modify post 456 to add a rating of 5 stars and update the description"

`generate_image`

基于文本提示，使用FLUX PRO 1.1模型生成AI图像。此工具可创建具有自动提示增强功能的高质量电影风格图像。

参数：

prompt （必填）：描述要生成的图像的文本提示（1-1000个字符）
width （可选）：生成图像的宽度（像素）（256-2048，默认值：1024）
height （可选）：生成图像的高度（像素）（256-2048，默认值：1024）
outputFormat （可选）：输出格式-“jpeg”或“png”（默认：“jpeg”）

克劳德用法示例：

"Generate an image of a cozy coffee shop interior with warm lighting"
"Create a 1920x1080 image of a mountain landscape at sunset"
"Make an image showing a bustling farmers market with fresh produce"

注：需要 BFL_API_KEY 要使用Black Forest Labs API密钥配置的环境变量。

`search_image`

使用SerpAPI搜索现有图像并返回高质量图像URL。此工具搜索谷歌图像，过滤质量结果，验证可访问性，并在需要时返回Unsplash。

参数：

query （必填）：图像搜索查询（1-200个字符）

克劳德用法示例：

"Search for an image of 'mountain landscape'"
"Find a photo of 'coffee shop interior'"
"Look for an image of 'vintage car'"

注：两者都需要 SERP_API_KEY 和 UNSPLASH_ACCESS_KEY 要配置的环境变量。

AI日志记录（可选）

MCP服务器可以自动将所有工具调用记录到YouMap API，以进行监控、调试和分析。此功能是可选的，需要额外的配置。

配置

添加以下环境变量以启用日志记录：

YOUMAP_API_URL=https://api.youmap.com/api/v1
YOUMAP_INTERNAL_API_KEY=your-internal-api-key-here

记录的内容

对于每次工具调用，都会记录以下信息：

关联ID：将工具调用链接到原始用户提示
工具名称：调用了哪个工具（例如。， create_map, list_posts)
参数：传递给工具的输入参数
响应：工具返回的结果
持续时间：执行时间（毫秒）
成功/错误：呼叫是成功还是失败
序列号：单个请求中的工具调用顺序
客户端ID：发出请求的OAuth客户端

益处

完全可追溯性：跟踪用户提示→ 人工智能处理→ 工具调用→ 结果
调试错误：看看失败的原因
性能监控：跟踪工具执行时间
使用情况分析：了解哪些工具最常用

查询日志

日志可以通过YouMap API的内部端点查询：

# Get recent logs
GET /internal/ai-logs/combined?limit=50

# Filter by tool name
GET /internal/ai-logs/combined?toolName=create_map

# Get tool statistics
GET /internal/ai-logs/statistics/tools?days=7

注：如果未配置日志环境变量，MCP服务器将正常工作，但不会记录工具调用。

发展

设置

git clone https://github.com/YouMap-app/youmap-mcp.git
cd youmap-mcp
npm install

发展模式

npm run dev

构建

npm run build

测试MCP服务器

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npm run dev

贡献

复刻仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

支持

如需支持，请访问

Youmap MCP

快速接入

详细介绍

YouMap MCP服务器

安装

全局安装（推荐）

本地安装

用法

使用克劳德桌面

使用API密钥（推荐）

使用OAuth凭据（传统）

环境变量

身份验证（选择一个）

配置

可选-图像API

认证

API密钥验证（推荐）

OAuth 2.0身份验证（传统）

HTTP服务器模式

端点

API密钥验证

OAuth身份验证

可用工具

create_map

create_post

create_action

list_actions

list_posts

list_maps

update_action

update_post

generate_image

search_image

AI日志记录（可选）

配置

记录的内容

益处

查询日志

发展

设置

发展模式

构建

测试MCP服务器

贡献

许可证

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`create_map`

`create_post`

`create_action`

`list_actions`

`list_posts`

`list_maps`

`update_action`

`update_post`

`generate_image`

`search_image`