Marvel MCP Server using Azure Functions

<div align="center">

<img src="./images/captain-america.jpg" alt="" align="center" height="96" />

# 使用 Azure Functions 的 Marvel MCP 服务器

[![在 GitHub Codespaces 中打开项目](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/danwahlin/marvel-mcp?hide_repo_select=true&ref=main&quickstart=true)
![Node 版本](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
[![许可证](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)

[特性](#features) • [工具](#tools) • [设置](#setup) • [配置 MCP 主机](#configuring-an-mcp-host)

</div>

用于 [Marvel Developer API](https://developer.marvel.com/documentation/getting_started) 的 MCP 服务器，支持与角色和漫画数据进行交互。*该项目的主要目标是展示如何使用 Azure Functions 托管的 MCP 服务器与 API 进行交互。*

> **注意**：此 MCP 服务器使用的所有数据均来自 [官方 Marvel API](https://developer.marvel.com/documentation/getting_started)，并且归 Marvel 所有。此项目与 Marvel 没有任何关联。

<a name="features"></a>
## 🔧 特性

- **列出 Marvel 角色**：支持 `nameStartsWith`、`limit`、`comics`、`series` 等过滤器。
- **按 ID 获取 Marvel 角色**：使用 `characterId` 获取任何角色的详细信息。
- **获取角色的漫画**：获取以特定角色为主角的漫画列表，并具有各种过滤器，如 `format`、`dateRange` 等。
- **基于工具的 MCP 集成**：将此服务器注册到模型上下文协议 (MCP) 工具（VS Code、Claude 等）。
- **环境配置**：使用 `.env` 文件来管理环境变量，如 `MARVEL_PUBLIC_KEY`、`MARVEL_PRIVATE_KEY` 和 `MARVEL_API_BASE`。

<a name="tools"></a>
## 🧰 工具

### 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`（数字）：角色的唯一 ID。
  - 可选过滤器：
    - `format`、`formatType`（字符串）：按漫画格式（例如，`comic`、`hardcover`）进行过滤。
    - `noVariants`、`hasDigitalIssue`（布尔值）：用于排除变体或仅包含数字版本的标志。
    - `dateDescriptor`（字符串）：预定义的日期范围，如 `thisWeek`、`nextWeek`。
    - `dateRange`（字符串）：自定义日期范围，格式为 `YYYY-MM-DD,YYYY-MM-DD`。
    - `title`、`titleStartsWith`（字符串）：按标题或标题前缀进行过滤。
    - `startYear`、`issueNumber`、`digitalId`（数字）：数字过滤器。
    - `diamondCode`、`upc`、`isbn`、`ean`、`issn`（字符串）：标识符过滤器。
    - `creators`、`series`、`events`、`stories`、`sharedAppearances`、`collaborators`（字符串）：以逗号分隔的相关实体 ID 列表。
    - `orderBy`（字符串）：用于对结果进行排序的字段，例如 `title` 或 `-modified`。
    - `limit`、`offset`（数字）：分页选项。
- **返回**：包含以指定角色为主角的漫画的 JSON 响应。有关详细信息，请参见 `src/schemas.ts` 中的 `ComicDataWrapperSchema`。

### 4. `get_comics` 📖🕵️‍♂️
- **描述**：获取 Marvel 漫画列表，带有可选过滤器。
- **输入**：
  - `format`（可选字符串）：按期数格式（例如，`comic`、`digital comic`、`hardcover`）进行过滤。
  - `formatType`（可选字符串）：按期数格式类型（`comic` 或 `collection`）进行过滤。
  - `noVariants`（可选布尔值）：从结果集中排除变体（备用封面、二次印刷、导演剪辑版等）。
  - `dateDescriptor`（可选字符串）：返回预定义日期范围内的漫画（`lastWeek`、`thisWeek`、`nextWeek`、`thisMonth`）。
  - `dateRange`（可选字符串）：返回自定义日期范围内的漫画。日期必须指定为 `YYYY-MM-DD,YYYY-MM-DD`。
  - `title`（可选字符串）：仅返回标题与输入匹配的系列中的期数。
  - `titleStartsWith`（可选字符串）：仅返回标题以输入开头的系列中的期数。
  - `startYear`（可选数字）：仅返回系列开始年份与输入匹配的期数。
  - `issueNumber`（可选数字）：仅返回系列期数与输入匹配的期数。
  - `diamondCode`、`digitalId`、`upc`、`isbn`、`ean`、`issn`（可选字符串）：按各种标识符进行过滤。
  - `hasDigitalIssue`（可选布尔值）：仅包括可数字化的结果。
  - `modifiedSince`（可选字符串）：仅返回自指定日期（ISO 8601 格式）以来修改的漫画。
  - `creators`、`characters`、`series`、`events`、`stories`、`sharedAppearances`、`collaborators`（可选字符串）：以逗号分隔的 ID 列表，用于按相关实体进行过滤。
  - `orderBy`（可选字符串）：按一个或多个字段对结果集进行排序。在值中添加“-”以按降序排序（例如，`title`、`-modified`）。
  - `limit`（可选数字）：将结果集限制为指定数量的资源（默认值：20，最大值：100）。
  - `offset`（可选数字）：跳过结果集中指定数量的资源。
- **返回**：包含匹配漫画的 JSON 响应。有关详细信息，请参见 `src/schemas.ts` 中的 `ComicDataWrapperSchema`。

### 5. `get_comic_by_id` 🆔📘
- **描述**：按其唯一 ID 获取单个 Marvel 漫画。
- **输入**：
  - `comicId`（数字）：漫画的唯一 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`。

<a name="setup"></a>
## 🛠️ 设置

注册一个 [Marvel Developer API](https://developer.marvel.com/documentation/getting_started) 帐户并获取您的公共和私有 API 密钥。

如果您想直接在 MCP 主机中使用 MCP 服务器，请跳转到 [与 GitHub Copilot 一起使用](#use-with-github-copilot) 或 [与 Claude Desktop 一起使用](#use-with-claude-desktop) 部分。

### 在本地运行服务器

1. 需要 Azure Storage Emulator。 有两种选择：

    - 在 Docker 容器中启动 Azurite：

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

    - 您可以使用 [Azurite VS Code 扩展](https://marketplace.visualstudio.com/items/?itemName=Azurite.azurite)。 安装扩展后，通过 VS Code 命令面板运行 `Azurite: Start`。

2. 克隆此存储库：

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

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

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

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

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

    ```bash
    npm install
    npm run build
    ```

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

    ```bash
    npm start
    ```

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

    ```bash
    # 启动 MCP Inspector
    npx @modelcontextprotocol/inspector node build/index.js
    ```

    在浏览器中访问控制台中显示的 MCP Inspector URL：
    - 将 `Transport Type` 更改为 `SSE`。
    - 输入 `http://0.0.0.0:7071/runtime/webhooks/mcp/sse` 作为 URL。
    - 选择 `Connect` 按钮。
    - 选择 `List Tools`。
    - 选择一个工具进行试用。

<a name="configuring-an-mcp-host"></a>
## 配置 MCP 主机

### 与 Claude Desktop 一起使用

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

```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，它将发现现有的 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) 漫画中？
   

   注意：如果您看到“抱歉，响应已被负责任的 AI 服务过滤。”，请尝试再次运行或重新措辞提示。