<div align="center">

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

Marvel MCP 服务器

特性 • 工具 • 设置 • 配置 MCP 主机

</div>

用于 Marvel Developer API 的 MCP 服务器，支持与角色和漫画数据进行交互。该项目的主要目标是展示如何使用 MCP 服务器与 API 进行交互。

注意: 此 MCP 服务器使用的所有数据均来自 官方 Marvel API，并归 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 帐户并获取您的公共和私有 API 密钥。

如果您想直接在 MCP 主机中运行它，请跳转到 与 Claude Desktop 一起使用 或 与 GitHub Copilot 一起使用 部分。

在本地使用 MCP Inspector 运行服务器

如果您想在本地运行 MCP Inspector 来测试服务器，请按照以下步骤操作：

1. 克隆此存储库：

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

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

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

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

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

   npm install
   npm run build
   

5. (可选) 要使用 MCP Inspector 试用服务器，请运行以下命令：

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

   在浏览器中访问控制台中显示的 MCP Inspector URL。将 Arguments 更改为 dist/index.js 并选择 Connect。选择 List Tools 以查看可用的工具。

<a name="configuring-an-mcp-host"></a>

配置 MCP 主机

与 Claude Desktop 一起使用

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

{
  "mcpServers": {
    "marvel-mcp": {
      "type": "stdio",
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@codewithdan/marvel-mcp"
        // "/PATH/TO/marvel-mcp/dist/index.js"
      ],
      "env": {
        "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
        "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
        "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
      }
    }
  }
}

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Marvel MCP Server：

npx -y @smithery/cli install @DanWahlin/marvel-mcp --client claude

与 GitHub Copilot 一起使用 (VS Code Insiders)

注意: 如果您已经使用 Claude Desktop 启用了 MCP 服务器，请在您的 VS Code 设置中添加 chat.mcp.discovery.enabled: true，它将发现现有的 MCP 服务器列表。

如果您想将 MCP 服务器与特定存储库关联，请创建一个包含以下内容的 .vscode/mcp.json 文件：

{
  "inputs": [],
  "servers": {
     "marvel-mcp": {
         "command": "npx",
         // "command": "node",
         "args": [
             "-y",
             "@codewithdan/marvel-mcp"
             // "/PATH/TO/marvel-mcp/dist/index.js"
         ],
         "env": {
             "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
             "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
             "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
         }
     }
  }
}

如果您想将 MCP 服务器与所有存储库关联，请将以下内容添加到您的 VS Code 用户设置 JSON：

"mcp": {
 "servers": {
     "marvel-mcp": {
         "command": "npx",
         // "command": "node",
         "args": [
             "-y",
             "@codewithdan/marvel-mcp"
             // "/PATH/TO/marvel-mcp/dist/index.js"
         ],
         "env": {
             "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
             "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
             "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
         }
     },
 }
},
"chat.mcp.discovery.enabled": true,

在 GitHub Copilot 中使用工具

1. 现在 MCP 服务器是可发现的，打开 GitHub Copilot 并选择 Agent 模式（而不是 Chat 或 Edits）。

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

3. 选择“🛠️”按钮以查看所有可能的工具，包括来自此存储库的工具。

4. 在聊天中提出一个自然会调用其中一个工具的问题，例如：

   列出 10 个漫威角色。包括图片。
   
   金刚狼出现在哪些漫画中？
   
   复仇者联盟漫画中出现了哪些角色？
   
   哪些角色出现在《树篱骑士 II：誓言之剑》(2007) 漫画中？
   

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