Marvel MCP Server using Azure Functions

面向 Marvel Developer API 的 MCP 服务，可与角色和漫画数据交互。本项目的主要目标是展示如何使用托管在 Azure Functions 上的 MCP 服务与 API 交互。

注意：此 MCP 服务使用的所有数据均来自 Marvel 官方 API，且归 Marvel 所有。本项目与 Marvel 没有任何关联。

🔧 功能

• 列出 Marvel 角色：支持 nameStartsWith、limit、comics、series 等筛选条件。
• 按 ID 获取 Marvel 角色：使用 characterId 获取任意角色的详细信息。
• 获取角色的漫画：获取包含指定角色的漫画列表，并支持 format、dateRange 等多种筛选条件。
• 基于工具的 MCP 集成：将此服务注册到 Model Context Protocol（MCP）工具中（VS Code、Claude 等）。
• 环境配置：使用 .env 文件管理 MARVEL_PUBLIC_KEY、MARVEL_PRIVATE_KEY 和 MARVEL_API_BASE 等环境变量。

🧰 工具

1. get_characters 🔍🦸‍♂️

• 描述：获取 Marvel 角色，并可选择使用筛选条件。
• 输入：
  • name（可选字符串）：角色的完整名称。
  • nameStartsWith（可选字符串）：名称以指定字符串开头的角色。
  • modifiedSince（可选字符串）：ISO 8601 日期字符串，用于筛选自该日期以来有过修改的角色。
  • comics、series、events、stories（可选字符串）：以逗号分隔的 ID 列表，用于按相关实体筛选。
  • orderBy（可选字符串）：用于排序结果的字段，例如 name 或 -modified。
  • limit（可选数字）：要返回的最大结果数（1–100）。
  • offset（可选数字）：分页时要跳过的结果数。
• 返回值：包含匹配角色的 JSON 响应。详情请参阅 src/schemas.ts 中的 CharacterDataWrapperSchema。

2. get_character_by_id 🆔🧑‍🎤

• 描述：按唯一 ID 获取 Marvel 角色。
• 输入：
  • characterId（数字）：角色的唯一 ID。
• 返回值：包含角色详细信息的 JSON 响应。详情请参阅 src/schemas.ts 中的 CharacterDataWrapperSchema。

3. get_comics_for_character 📚🎭

• 描述：获取包含特定角色的漫画，可选筛选条件。
• 输入：
  • characterId（number）：角色的唯一 ID。
  • 可选筛选条件：
    • format、formatType（string）：按漫画格式筛选（例如，comic、hardcover）。
    • noVariants、hasDigitalIssue（boolean）：用于排除变体版本或仅包含数字版的标志。
    • dateDescriptor（string）：预定义的日期范围，例如 thisWeek、nextWeek。
    • dateRange（string）：自定义日期范围，格式为 YYYY-MM-DD,YYYY-MM-DD。
    • title、titleStartsWith（string）：按标题或标题前缀筛选。
    • startYear、issueNumber、digitalId（number）：数值筛选条件。
    • diamondCode、upc、isbn、ean、issn（string）：标识符筛选条件。
    • creators、series、events、stories、sharedAppearances、collaborators（string）：以逗号分隔的相关实体 ID 列表。
    • orderBy（string）：用于对结果排序的字段，例如 title 或 -modified。
    • limit、offset（number）：分页选项。
• 返回值：包含指定角色相关漫画的 JSON 响应。详情请参阅 src/schemas.ts 中的 ComicDataWrapperSchema。

4. get_comics 📖🕵️‍♂️

• 描述：获取 Marvel 漫画列表，可选筛选条件。
• 输入：
  • format（可选 string）：按单期漫画格式筛选（例如，comic、digital comic、hardcover）。
  • formatType（可选 string）：按单期漫画格式类型筛选（comic 或 collection）。
  • noVariants（可选 boolean）：从结果集中排除变体版本（替代封面、二次印刷版、导演剪辑版等）。
  • dateDescriptor（可选 string）：返回预定义日期范围内的漫画（lastWeek、thisWeek、nextWeek、thisMonth）。
  • dateRange（可选 string）：返回自定义日期范围内的漫画。日期必须采用 YYYY-MM-DD,YYYY-MM-DD 格式。
  • title（可选 string）：仅返回系列标题与输入相符的单期漫画。
  • titleStartsWith（可选 string）：仅返回系列标题以输入内容开头的单期漫画。
  • startYear（可选 number）：仅返回系列起始年份与输入相符的单期漫画。
  • issueNumber（可选 number）：仅返回系列期号与输入相符的单期漫画。
  • diamondCode、digitalId、upc、isbn、ean、issn（可选 string）：按各种标识符筛选。
  • hasDigitalIssue（可选 boolean）：仅包含可获取数字版的结果。
  • modifiedSince（可选 string）：仅返回自指定日期以来修改过的漫画（ISO 8601 格式）。
  • creators、characters、series、events、stories、sharedAppearances、collaborators（可选 string）：以逗号分隔的 ID 列表，用于按相关实体筛选。
  • orderBy（可选 string）：按一个或多个字段对结果集排序。在值前添加 - 可按降序排序（例如，title、-modified）。
  • limit（可选 number）：将结果集限制为指定数量的资源（默认值：20，最大值：100）。
  • offset（可选 number）：跳过结果集中的指定数量资源。
• 返回值：包含匹配漫画的 JSON 响应。详情请参阅 src/schemas.ts 中的 ComicDataWrapperSchema。

5. get_comic_by_id 🆔📘

• 描述：通过唯一 ID 获取单本 Marvel 漫画。
• 输入：
  • comicId（number）：漫画的唯一 ID。
• 返回值：包含漫画详情的 JSON 响应。详情请参阅 src/schemas.ts 中的 ComicDataWrapperSchema。

6. get_characters_for_comic 🦸‍♀️📖

• 描述：获取出现在指定漫画中的 Marvel 角色。
• 输入：
  • comicId（数字）：漫画的唯一 ID。
  • 可选筛选条件：
    • name（可选字符串）：按角色全名筛选。
    • nameStartsWith（可选字符串）：筛选名称以指定字符串开头的角色。
    • modifiedSince（可选字符串）：ISO 8601 日期字符串，用于筛选自此日期以来修改过的角色。
    • series、events、stories（可选字符串）：以逗号分隔的相关实体 ID 列表，用于筛选。
    • orderBy（可选字符串）：用于排序结果的字段，例如 name 或 -modified。
    • limit（可选数字）：返回结果的最大数量（1–100）。
    • offset（可选数字）：分页时跳过的结果数量。
• 返回：包含出现在指定漫画中的角色的 JSON 响应。详情请参阅 src/schemas.ts 中的 CharacterDataWrapperSchema。

🛠️ 设置

注册 Marvel Developer API 账号，并获取你的公共和私有 API 密钥。

如果要直接在 MCP 主机中使用 MCP 服务，请跳转到与 GitHub Copilot 配合使用或与 Claude Desktop 配合使用部分。

在本地运行服务

1. 需要 Azure Storage Emulator。可选择以下两种方式：

   • 在 Docker 容器中启动 Azurite：

     docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 \
         mcr.microsoft.com/azure-storage/azurite
     

   • 也可以使用 Azurite VS Code 扩展。安装扩展后，通过 VS Code 命令面板运行 Azurite: Start。

2. 克隆此仓库：

   git clone https://github.com/DanWahlin/marvel-mcp-azure-functions
   

3. 将 .env.template 重命名为 .env。

4. 将 Marvel API 公共和私有密钥添加到 .env 文件中。

   MARVEL_PUBLIC_KEY=YOUR_PUBLIC_KEY
   MARVEL_PRIVATE_KEY=YOUR_PRIVATE_KEY
   MARVEL_API_BASE=https://gateway.marvel.com/v1/public
   

5. 安装所需依赖项并构建项目。

   npm install
   npm run build
   

6. 在本地启动 Azure Functions 主机：

   npm start
   

7. （可选）若要使用 MCP Inspector 试用 MCP 服务，请运行以下命令：

   # Start the MCP Inspector
   npx @modelcontextprotocol/inspector node build/index.js
   

   在浏览器中访问控制台显示的 MCP Inspector URL：

   • 将 Transport Type 更改为 SSE。
   • 在 URL 栏中输入 http://0.0.0.0:7071/runtime/webhooks/mcp/sse。
   • 点击 Connect 按钮。
   • 点击 List Tools。
   • 选择一个工具进行试用。

配置 MCP 主机

与 Claude Desktop 配合使用

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "marvel-mcp": {
      "type": "sse",
      "url": "http://0.0.0.0:7071/runtime/webhooks/mcp/sse"
    }
  }
}

在 VS Code 中与 GitHub Copilot 配合使用

注意：如果已在 Claude Desktop 中启用 MCP 服务，请在 VS Code 设置中添加 chat.mcp.discovery.enabled: true，VS Code 就会发现现有的 MCP 服务列表。

如果要将 MCP 服务关联到特定仓库，请创建 .vscode/mcp.json 文件，并添加以下内容：

{
  "inputs": [],
  "servers": {
     "marvel-mcp": {
       "type": "sse",
       "url": "http://0.0.0.0:7071/runtime/webhooks/mcp/sse"
     }
  }
}

如果要将 MCP 服务关联到所有仓库，请将以下内容添加到 VS Code 用户设置 JSON 中：

"mcp": {
 "servers": {
   "marvel-mcp": {
     "type": "sse",
     "url": "http://0.0.0.0:7071/runtime/webhooks/mcp/sse"
   }
 }
}

部署到 Azure 以使用远程 MCP

运行此 azd 命令来预配函数应用及所需的任何 Azure 资源，并部署代码：

azd up

你可以选择在此示例中使用 VNet。为此，请在运行 azd up 之前执行以下操作：

azd env set VNET_ENABLED true

此外，可以使用 API Management 来增强 MCP 服务的安全性并实施策略，也可以使用 App Service 内置身份验证来设置你喜欢的 OAuth 提供商，包括 Entra。

在 GitHub Copilot 中使用工具

1. 现在 MCP 服务已可被发现，打开 GitHub Copilot 并选择 Agent 模式（而不是 Ask 或 Edit）。

2. 选择 Copilot 聊天文本框中的“刷新”按钮，以刷新服务列表。

3. 选择“🛠️”按钮，查看所有可用工具，包括此代码库中的工具。

4. 在聊天中输入一个能自然调用某个工具的问题，例如：

   列出 10 位漫威角色，并附上图片。
   
   金刚狼出现在哪些漫画中？
   
   哪些角色出现在《复仇者联盟》漫画中？
   
   漫画《Hedge Knight II: Sworn Sword (2007)》中有哪些角色？
   

   注意：如果看到“抱歉，响应已被 Responsible AI Service 过滤。”，请尝试重新运行或改写提示词。