概述

Mapfolio MCP 服务器是一个 Model Context Protocol (MCP) 服务器，使 AI 助手和其他 MCP 兼容客户端能够与 Mapfolio 的数据和操作进行交互。它提供对公司、项目、用户、LinkedIn 配置文件和 administrative 功能的编程访问。

什么是 MCP？

Model Context Protocol (MCP) 是一个开放协议，使 AI 助手能够安全地访问外部数据源和工具。MCP 服务器通过标准化接口公开功能，允许 AI 助手：

查询和检索数据
执行操作
访问资源
与外部系统集成

功能

Mapfolio MCP 服务器提供全面的功能：

公司数据

使用高级过滤器搜索公司
按 ID 获取公司详细信息
按州和起始字母检索公司
获取随机公司用于采样
访问公司访问统计

项目管理

创建和管理项目
列出和过滤用户项目
更新项目详细信息
删除项目
向项目添加和删除公司

用户配置文件

获取用户配置文件信息
更新配置文件设置
列出用户项目
管理 API 密钥

LinkedIn 集成

获取 LinkedIn 配置文件数据
搜索 LinkedIn 配置文件
访问连接信息
查看配置文件版本历史
获取 LinkedIn 公司数据

管理操作

列出所有用户（仅管理员）
创建新用户（仅管理员）
管理 API 密钥（仅管理员）
访问管理仪表板统计

统计

获取聚合公司统计
查看州级计数
访问基于字母的计数
获取两个字母组合统计

安装

先决条件

Node.js >= 20.0.0
npm >= 10.0.0
访问 Mapfolio Supabase 实例

设置

安装依赖项：

cd mcp-server
npm install

配置环境变量：

cp .env.example .env

编辑 .env 并配置：

# Mapfolio API URL (默认: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# 传输类型: 'stdio' (默认) 或 'http' 用于远程访问
MCP_TRANSPORT=stdio

# HTTP 端口 (仅在 MCP_TRANSPORT=http 时使用)
MCP_HTTP_PORT=3001

# 可选: 默认身份验证 (可通过 MCP 上下文或 HTTP 标头提供)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here

构建服务器：

npm run build

使用

运行服务器

本地开发 (stdio 传输)

MCP 服务器默认使用 stdio 传输（标准 MCP 协议）：

npm start

用于自动重新加载的开发：

npm run dev

HTTP 传输 (用于远程访问)

要在本地测试中使用 HTTP 传输运行服务器：

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

这将在端口 3001 上启动一个 HTTP 服务器，接受通过 HTTP POST 的 JSON-RPC 2.0 请求。

Vercel 部署 (远程访问)

MCP 服务器在部署到 Vercel 时自动通过 HTTP 可用：

端点: https://your-app.vercel.app/api/mcp
协议: 通过 HTTP POST 的 JSON-RPC 2.0
身份验证: 通过 X-API-Key 标头或 Authorization: Bearer <token> 标头

示例请求：

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

MCP 客户端配置

Claude Desktop

本地部署：

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

通过 MCP 设置配置：

命令: node
Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
环境变量:
- MAPFOLIO_API_URL: https://mapfolio.app
- MAPFOLIO_API_KEY: 您的 API 密钥（可选）

身份验证

服务器支持两种身份验证方法：

API 密钥身份验证

API 密钥以 mapf_ 为前缀，可以：

通过 MAPFOLIO_API_KEY 环境变量设置
在工具调用中通过 apiKey 参数按请求传递

JWT 令牌身份验证

Supabase JWT 令牌可以：

通过 MAPFOLIO_JWT_TOKEN 环境变量设置
在工具调用中通过 jwtToken 参数按请求传递

身份验证优先级

HTTP 传输: 标头（X-API-Key 或 Authorization）优先
按请求凭据（工具参数中的 apiKey 或 jwtToken）
环境变量（MAPFOLIO_API_KEY 或 MAPFOLIO_JWT_TOKEN）

HTTP 传输身份验证

使用 HTTP 端点 (/api/mcp) 时，通过 HTTP 标头提供身份验证：

API 密钥: X-API-Key: mapf_your_api_key
JWT 令牌: Authorization: Bearer your_jwt_token

可用工具

服务器在 6 个类别中提供 30+ 工具：

公司工具

search_companies - 使用过滤器搜索
get_company - 按 ID 获取公司
get_companies_by_canton_letter - 按州和字母获取
get_random_companies - 获取随机样本
get_company_visits - 获取访问统计

项目工具

create_project - 创建新项目
list_projects - 列出用户项目
get_project - 获取项目详细信息
update_project - 更新项目
delete_project - 删除项目
add_companies_to_project - 添加公司
remove_companies_from_project - 删除公司

用户工具

get_user_profile - 获取配置文件
update_user_profile - 更新配置文件
get_user_projects - 列出项目
get_user_api_keys - 列出 API 密钥

LinkedIn 工具

get_linkedin_profile - 获取配置文件
search_linkedin_profiles - 搜索配置文件
get_linkedin_connections - 获取连接
get_linkedin_profile_versions - 获取版本历史
get_linkedin_companies - 获取公司数据

管理工具 (仅管理员)

list_all_users - 列出所有用户
create_user - 创建用户
get_user_details - 获取用户详细信息
list_api_keys - 列出所有 API 密钥
create_api_key - 创建 API 密钥
revoke_api_key - 撤销 API 密钥
get_admin_stats - 获取管理统计

统计工具

get_company_stats - 获取聚合统计
get_canton_counts - 获取州计数
get_letter_counts - 获取字母计数
get_two_letter_counts - 获取两个字母计数

资源

服务器提供基于资源的访问：

mapfolio://company/{id} - 公司数据
mapfolio://project/{id} - 项目数据
mapfolio://user/{id} - 用户配置文件
mapfolio://linkedin-profile/{id} - LinkedIn 配置文件

资源可以通过查询参数包含身份验证：

mapfolio://company/{id}?apiKey=mapf_...
mapfolio://company/{id}?jwtToken=...

使用示例

搜索公司

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

创建项目

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

获取公司详细信息

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

错误处理

所有工具都以一致的格式返回错误：

{
  "error": "错误消息"
}

常见错误场景：

401 未授权: 无效或缺少身份验证
403 禁止: 权限不足
404 未找到: 未找到资源
500 内部服务器错误: 服务器端错误

仅 API 架构

MCP 服务器使用 对 mapfolio.app 的 HTTP 请求而不是直接数据库访问。这意味着：

✅ 不需要 Supabase 凭据 - 仅使用 API URL 和 API 密钥即可工作
✅ 易于 Vercel 部署 - 作为 serverless 函数部署
✅ 安全 - 所有请求都通过 Mapfolio 的 API 进行身份验证
✅ 可扩展 - 受益于 Mapfolio 的 API 速率限制和缓存

目前通过 API 可用

✅ 公司搜索和检索
✅ 公司统计（州计数、字母计数）
✅ 随机公司
✅ 公司访问

即将推出 (需要 API 端点)

⏳ 项目管理（创建、列出、更新、删除）
⏳ 用户配置文件管理
⏳ LinkedIn 配置文件访问
⏳ 管理操作

这些功能将返回有用的错误消息，直到创建 API 端点。

安全注意事项

API 密钥: 安全存储，永远不要提交到版本控制
JWT 令牌: 令牌过期，适当处理刷新
API 速率限制: 遵守 Mapfolio 的 API 速率限制
仅 HTTPS: 始终对 API 请求使用 HTTPS
管理操作: 需要明确的管理员身份验证（当端点可用时）

开发

类型检查

npm run type-check

构建

npm run build

开发模式

npm run dev

文档

有关完整文档，请参阅 MCP 服务器 README。

支持

如有问题或疑问：

GitHub Issues: [mapfolio repository]
电子邮件: support@mapfolio.app

许可证

MIT