项目简介

Hellō 管理 MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在以标准化方式将 Hellō 开发者平台的功能暴露给大型语言模型（LLM）客户端。它允许开发者通过 AI 助手直接创建和管理 Hellō 应用程序，例如创建应用、更新配置、生成客户端密钥以及上传徽标等。该服务器处于 Beta 阶段，积极欢迎反馈和贡献。

主要功能点

上下文感知操作： 每个工具调用都会自动包含您的开发者个人资料、团队和应用程序的完整上下文，无需手动传递，实现无缝操作。
统一应用管理： 提供一个强大的工具（'hello_manage_app'），用于执行所有应用生命周期操作，包括创建、读取、更新应用，生成客户端密钥，以及上传不同主题（亮/暗模式）的徽标。
安全 OAuth 集成： 支持基于浏览器的 OAuth 认证流程和 JWT 令牌验证，确保操作的安全性。
多传输协议支持： 可通过标准输入输出（Stdio）在本地运行，或通过 HTTP 协议远程访问，为不同的部署场景提供灵活性。
丰富的上下文资源： 提供 Hellō 平台的各种文档和指南作为可访问的资源，如快速入门、API 参考、徽标设计指南等，方便 AI 助手查询。
内置分析与灵活配置： 支持使用情况跟踪和性能监控，并通过环境变量（'HELLO_DOMAIN'、'HELLO_ADMIN'）提供灵活的环境配置。

安装步骤

您可以选择以下两种方式安装和运行 Hellō 管理 MCP 服务器：

1. 使用 NPM 包（推荐）

这是最快捷的启动方式，无需克隆仓库或手动安装依赖。

2. 本地开发设置

如果您希望从源代码运行或进行开发，请遵循以下步骤：

克隆仓库：

git clone https://github.com/hellocoop/admin-mcp
cd admin-mcp

安装依赖：
```
npm install
```

服务器配置（供 MCP 客户端连接使用）

MCP 服务器可以配置为通过两种主要传输方式运行：

NPM 包（最新版本） 这是通过 'npx' 命令从 npm 获取并运行服务器的方式。适用于您希望 MCP 客户端自动管理服务器进程的场景。

{
  "hello-admin-stdio": {
    "command": "npx",
            "args": ["-y", "@hellocoop/admin-mcp@latest"],
    "type": "stdio",
    "comment": "此配置通过npm命令在本地启动MCP服务器，使用stdio协议进行通信。"
  }
}

'command': 'npx' - 用于执行 npm 包的命令。
'args': '["-y", "@hellocoop/admin-mcp@latest"]' - 传递给 'npx' 的参数，'-y' 自动确认安装，'@hellocoop/admin-mcp@latest' 指定运行最新版本的服务器包。
'type': 'stdio' - 表示使用标准输入/输出协议进行通信。

HTTP 传输（远程） 这是连接到 Hellō 官方托管的远程 HTTP MCP 服务器。适用于您不希望在本地运行服务器进程，而是直接访问在线服务的场景。

{
  "hello-admin-http": {
            "url": "https://admin-mcp.hello.coop/",
    "type": "http",
    "comment": "此配置通过HTTP协议连接到 Hellō 官方托管的远程 MCP 服务器。"
  }
}

'url': 'https://admin-mcp.hello.coop/' - 远程 MCP 服务器的 HTTP 端点 URL。
'type': 'http' - 表示使用 HTTP 协议进行通信。

本地开发版本（Node.js 运行时） 如果您从源代码克隆了仓库，并希望运行本地开发版本，可以使用以下配置：

{
  "hello-admin-local": {
    "command": "node",
            "args": ["path/to/your/repo/admin-mcp/src/stdio.js"],
    "type": "stdio",
    "comment": "此配置通过Node.js在本地启动MCP服务器的开发版本，使用stdio协议进行通信。请将 'path/to/your/repo' 替换为您的实际仓库路径。"
  }
}

'command': 'node' - 用于运行 Node.js 脚本的命令。
'args': '["path/to/your/repo/admin-mcp/src/stdio.js"]' - 指定要运行的本地 MCP 服务器脚本路径。请务必将 'path/to/your/repo' 替换为您的实际项目路径。
'type': 'stdio' - 表示使用标准输入/输出协议进行通信。

基本使用方法

作为 MCP 客户端（例如 AI 助手），您可以通过 JSON-RPC 请求与 Hellō 管理 MCP 服务器进行交互。以下是一些核心功能的使用示例：

获取可用工具列表： 客户端可以发送 'tools/list' 请求来发现服务器提供的所有工具及其详细架构。
- 作用： 了解服务器能够执行哪些操作。
- 示例 (概念性)： AI 助手在不知道能做什么时，会首先询问此列表。
调用 'hello_manage_app' 工具： 这是该服务器的核心工具，允许您执行多种 Hellō 应用管理操作。
- 创建新应用： AI 助手可以调用 'hello_manage_app' 工具，并指定 'action: "create"' 及应用名称、重定向 URI 等参数。
  - 示例： "创建一个名为 '我的新AI应用' 的 Hellō 应用，开发环境重定向 URI 为 'http://localhost:3000/callback'。"
- 读取应用详情： AI 助手可以调用 'hello_manage_app' 工具，并指定 'action: "read"' 及 'client_id' 来获取特定应用的详细信息。如果省略 'client_id'，将返回当前用户的 Hellō 开发者个人资料及所有关联应用。
  - 示例： "显示 ID 为 'app12345' 的应用详情。" 或 "列出我所有的 Hellō 应用和团队信息。"
- 更新应用配置： AI 助手可以调用 'hello_manage_app' 工具，并指定 'action: "update"' 及 'client_id' 和要修改的属性（如 'name'、'tos_uri'、'prod_redirect_uris' 等）。
  - 示例： "将 ID 为 'app12345' 的应用名称更新为 '更新后的AI应用'，并添加生产环境重定向 URI 'https://myapp.com/callback'。"
- 生成客户端密钥： AI 助手可以调用 'hello_manage_app' 工具，并指定 'action: "create_secret"' 及 'client_id' 来为应用生成一个新的客户端密钥。
  - 示例： "为 ID 为 'app12345' 的应用生成一个新的客户端密钥。"
- 上传应用徽标： AI 助手可以调用 'hello_manage_app' 工具，并指定 'action: "update_logo_from_data"' （提供 Base64 编码的徽标数据和 MIME 类型）或 'action: "update_logo_from_url"' （提供徽标 URL）。
  - 示例： "将 ID 为 'app12345' 的应用徽标更新为一张 PNG 图片，数据为 Base64 字符串。" 或 "从 'https://example.com/logo.png' 更新 ID 为 'app12345' 的应用徽标。"
获取可用资源列表： 客户端可以发送 'resources/list' 请求来获取服务器提供的所有文档和指南资源的列表。
- 作用： 帮助 AI 助手了解可用于回答问题或提供指导的外部信息。
- 示例 (概念性)： "有哪些 Hellō 的文档可以帮助我理解 OAuth 流程？"
读取特定资源： 客户端可以发送 'resources/read' 请求，指定资源的 URI 来获取其内容。
- 作用： 获取特定文档或指南的详细内容。
- 示例 (概念性)： "读取 'Hellō Quickstarts' 文档的内容。"

关键词