使用说明

项目简介

本项目 'marvel-mcp' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在演示如何使用 MCP 服务器与外部 API 进行交互。它通过连接漫威开发者API，提供了查询漫威漫画和角色数据的功能，并以 MCP 工具的形式暴露给支持 MCP 协议的客户端（如 GitHub Copilot Agent 模式、Claude 等）。

主要功能点

查询漫威角色: 支持根据名称、起始名称等条件检索漫威角色。
按ID查询角色: 根据角色 ID 获取角色的详细信息。
查询角色相关漫画: 获取特定角色参与的漫画列表，并支持多种漫画过滤器。
查询漫画列表: 获取漫威漫画列表，支持多种过滤器，如漫画格式、日期范围、标题等。
按ID查询漫画: 根据漫画 ID 获取单本漫画的详细信息。
查询漫画中的角色: 获取特定漫画中出现的角色列表。
生成漫画HTML页面: 根据漫画数据生成包含漫画封面的 HTML 页面，方便可视化展示。

安装步骤

获取 Marvel API 密钥: 访问 Marvel Developer API 注册并获取 Public Key 和 Private Key。

克隆仓库: 将 'marvel-mcp' 仓库克隆到本地。

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

配置环境变量:

复制 '.env.template' 文件并重命名为 '.env'。

打开 '.env' 文件，填入你申请的 Marvel API Public Key 和 Private Key。

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

安装依赖并构建: 运行以下命令安装项目依赖并构建项目。
```
npm install
npm run build
```

服务器配置

MCP 服务器需要配置到 MCP 客户端才能使用。以下分别是在 Claude Desktop 和 GitHub Copilot (VS Code Insiders) 中配置 'marvel-mcp' 服务器的配置信息。请注意，以下是配置信息，无需用户修改代码，只需复制到 MCP 客户端的配置文件中。

Claude Desktop 配置

修改 'claude_desktop_config.json' 文件，在 'mcpServers' 中添加 'marvel-mcp' 服务器配置。

{
  "mcpServers": {
    "marvel-mcp": {
      "type": "stdio",
      "command": "npx",  // 启动命令，使用 npx 运行
      "args": [
        "-y",
        "@codewithdan/marvel-mcp" //  运行 @codewithdan/marvel-mcp 包，前提是已全局安装或在项目依赖中
        // 如果本地运行，可以使用构建后的 index.js 文件路径，例如: "/PATH/TO/marvel-mcp/dist/index.js"
      ],
      "env": {
        "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",  //  Marvel API Public Key，请替换为你的密钥
        "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY", // Marvel API Private Key，请替换为你的密钥
        "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public" // Marvel API 基础 URL
      }
    }
  }
}

GitHub Copilot (VS Code Insiders) 配置

仓库级别配置 (推荐): 在你的代码仓库的 '.vscode' 目录下创建 'mcp.json' 文件，并添加以下内容。

{
  "inputs": [],
  "servers": {
     "marvel-mcp": {
         "command": "npx", // 启动命令，使用 npx 运行
         "args": [
             "-y",
             "@codewithdan/marvel-mcp" // 运行 @codewithdan/marvel-mcp 包，前提是已全局安装或在项目依赖中
             // 如果本地运行，可以使用构建后的 index.js 文件路径，例如: "/PATH/TO/marvel-mcp/dist/index.js"
         ],
         "env": {
             "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY", // Marvel API Public Key，请替换为你的密钥
             "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",// Marvel API Private Key，请替换为你的密钥
             "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public" // Marvel API 基础 URL
         }
     }
  }
}

用户级别配置: 打开 VS Code 设置 (Settings)，搜索 "mcp"，在 "User Settings" 的 JSON 编辑器中添加以下配置。

"mcp": {
  "servers": {
      "marvel-mcp": {
          "command": "npx", // 启动命令，使用 npx 运行
          "args": [
              "-y",
              "@codewithdan/marvel-mcp" // 运行 @codewithdan/marvel-mcp 包，前提是已全局安装或在项目依赖中
              // 如果本地运行，可以使用构建后的 index.js 文件路径，例如: "/PATH/TO/marvel-mcp/dist/index.js"
          ],
          "env": {
              "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY", // Marvel API Public Key，请替换为你的密钥
              "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",// Marvel API Private Key，请替换为你的密钥
              "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public" // Marvel API 基础 URL
          }
      },
  }
},
"chat.mcp.discovery.enabled": true, // 启用 MCP 服务器发现

注意:

'command' 和 'args' 配置指定了服务器的启动方式。这里使用 'npx @codewithdan/marvel-mcp' 可以直接运行已发布的 npm 包 '@codewithdan/marvel-mcp'。如果你想本地运行，可以将 'args' 修改为指向 'dist/index.js' 的路径，例如 '"/PATH/TO/marvel-mcp/dist/index.js"'，并且 'command' 可以改为 '"node"'。
'env' 配置中需要填入你的 Marvel API 密钥。

基本使用方法

确保 MCP 服务器已正确配置并启动。
在 GitHub Copilot 中切换到 Agent 模式 (而非 Chat 或 Edits 模式)。
点击 Copilot 聊天输入框旁边的刷新按钮，刷新工具列表，确保 'marvel-mcp' 服务器的工具被成功发现。
点击 "🛠️" 工具按钮，可以查看所有可用的工具，包括来自 'marvel-mcp' 服务器的工具。
在 Copilot 聊天框中输入自然语言问题，例如：
- 'List 10 marvel characters.' (列出10个漫威角色)
- 'What comics is Wolverine in?' (金刚狼出现在哪些漫画中？)
- 'Which characters appear in the Avengers comics?' (哪些角色出现在复仇者联盟漫画中？)
- 'What characters are in the Hedge Knight II: Sworn Sword (2007) comic?' (哪些角色出现在《雇佣骑士II：誓剑》(2007) 漫画中？)
Copilot Agent 会根据你的问题自动调用 'marvel-mcp' 服务器提供的工具来获取漫威数据，并返回结果。

关键词