使用说明

MCP工具目录

一个全面的Backstage插件，用于管理模型上下文协议（MCP）基础设施，提供对组织内MCP服务器、工具和工作负载的可见性。

🎯 项目概述

MCP工具目录通过三种新的实体类型扩展了Backstage，以提供对模型上下文协议基础架构的完全可见性：

🖥️ MCP服务器：人工智能能力提供商（如GitHub API服务器、文件系统服务器）
🔧 MCP工具：单个AI功能（例如，创建问题、读取文件、分析文本）
⚙️ MCP工作负荷：组合工作流（例如，项目设置自动化、内容管道）

✨ 特性

🔍 发现：浏览和发现基础架构中的MCP服务器
🔗 关系：可视化服务器、工具和工作负载之间的连接
✅ 验证：实体关系和引用的自动验证
🚀 整合：与Backstage目录和身份验证无缝集成
📊 管理：通过直观的UI管理工作负载工具关系
🏗️ 香草OpenShift就绪：在上游Backstage和标准OpenShift上工作，没有专有扩展
🔎 全局搜索：使用URL持久性搜索所有实体类型
♿ 无障碍：完整的ARIA标签、键盘导航和屏幕阅读器支持
📦 一个命令部署：使用单个脚本进行构建、推送、部署和测试

🧭 宪法对齐

安全第一：容器映像以非根目录运行，机密不在Git中，部署清单包括健康检查和深度防御的资源限制。
先配置：行为由Helm值驱动， console-extensions.json，以及 app-config 因此，在不重建插件的情况下，功能会因环境而异。
后台目录优先：MCP服务器、工具和工作负载被建模为标准的Backstage组件，将实体发现保持在现有的目录图中。
Vanilla OpenShift平台目标：图表、清单和控制台插件定义在vanilla OpenShift集群上工作不变；Red Hat Developer Hub的特定功能必须包括上游安全回退。
TypeScript首次开发：根 tsconfig.json 强制执行 strict: true 代码库使用TypeScript而不是JavaScript shims来提供新的逻辑。跑 npx tsc --noEmit 从repo根和 npx tsc --noEmit -p tsconfig.check.json 从 plugins/mcp-tools-catalog 以确保两个目标类型的安全。
Python工具的严格类型：任何Python自动化（例如辅助脚本）都必须附带Python 3.9+类型提示和传递 mypy --strict 在合并之前。

🏗️ 建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Server    │    │    MCP Tool     │    │  MCP Workload   │
│  (Component)    │    │  (Component)    │    │  (Component)    │
│ spec.type:      │    │ spec.type:      │    │ spec.type:      │
│  mcp-server     │◀───│  mcp-tool       │◀───│  service        │
│                 │    │                 │    │                 │
│ hasPart ────────┼───▶│ subcomponentOf  │    │ dependsOn ──────┤
└─────────────────┘    └─────────────────┘    └─────────────────┘

关系（标准后台）：

Tool → 服务器: spec.subcomponentOf 创造 partOf/hasPart 关系
工作量→ Tool: spec.dependsOn 创造 dependsOn/dependencyOf 关系
所有实体都是标准后台 Component 和蔼可亲 spec.type 价值观

📚 文档

完整文档索引 -按主题和受众组织的所有文档

快速链接:

🏗️ MERGE-ARCHITECTURE.md -目录+数据库合并的工作原理
✅ 已禁用-工具箱-已完成。.md -禁用/启用工具功能
🔐 认证.md -完整的身份验证指南
🚀 部署.md -部署指南

🚀 快速开始

先决条件

后台实例（v1.8+）
Node.js 18+
TypeScript 4.9+ strict 模式已启用
Vanilla OpenShift集群（不需要专有控制台扩展）

安装

安装插件：

cd your-backstage-app
yarn add @internal/plugin-mcp-tools-catalog

添加到您的Backstage应用程序：

// packages/app/src/App.tsx
import { McpCatalogPage } from '@internal/plugin-mcp-tools-catalog';

<Route path="/mcp-catalog" element={<McpCatalogPage />} />

注册实体处理器：

// packages/backend/src/plugins/catalog.ts
import { McpEntityProcessor } from '@internal/plugin-mcp-tools-catalog';

builder.addProcessor(new McpEntityProcessor());

配置插件：

# app-config.yaml
mcpCatalog:
  enabled: true
  ui:
    showRelationshipGraphs: true

注册您的第一台MCP服务器

创建 github-server.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: github-integration-server
  namespace: default
  description: "MCP server for GitHub API operations"
  labels:
    mcp-catalog.io/type: server
spec:
  type: mcp-server
  lifecycle: production
  owner: platform-team
  mcp:
    serverType: stdio
    endpoint: "docker run -i --rm ghcr.io/github/github-mcp-server"
    version: "1.0.0"
    capabilities:
      - tools
      - resources

📁 项目结构

mcp-tools-catalog/
├── plugins/mcp-tools-catalog/          # Main Backstage plugin
│   ├── src/
│   │   ├── components/                 # React components
│   │   ├── schemas/                   # Entity type definitions
│   │   ├── api/                       # API client and interfaces
│   │   ├── services/                  # Business logic
│   │   ├── processors/                # Backstage processors
│   │   └── utils/                     # Utilities and validation
│   ├── package.json
│   └── README.md
├── charts/mcp-tools-catalog/          # Helm charts for deployment
│   ├── templates/
│   └── values.yaml
├── integration-tests/                 # End-to-end tests
│   ├── tests/
│   └── cypress.config.js
├── specs/001-mcp-tools-catalog/       # Design documentation
│   ├── plan.md
│   ├── spec.md
│   ├── data-model.md
│   └── quickstart.md
└── README.md                          # This file

🧪 开发与测试

本地开发

# Clone repository
git clone <repository-url>
cd mcp-tools-catalog

# Install dependencies
yarn install

# Build plugin
cd plugins/mcp-tools-catalog
yarn build

# Run tests
yarn test

# Start development server
yarn dev

测试

# Unit tests
yarn test

# Integration tests
cd integration-tests
yarn cypress:run

# Lint and format
yarn lint

# Sanity tests (against deployed cluster)
./tests/sanity/quick-check.sh        # Quick health check (~30 seconds)
./tests/sanity/run-sanity-tests.sh   # Full test suite with detailed output

手动测试场景

实体注册：
- 注册MCP服务器，验证它是否出现在目录中
- 添加链接到服务器的工具，验证关系
- 创建工作负载引用工具，测试导航
关系管理：
- 从服务器导航→ 工具→ 工作量
- 测试双向关系显示
- 验证级联删除行为
搜索和筛选：
- 按实体类型（服务器/工具/工作负载）筛选
- 按名称、描述、标签搜索
- 测试高级过滤组合
错误处理：
- 测试断开的实体引用
- 验证错误消息和恢复
- 测试验证端点响应

🏭 部署

Vanilla OpenShift部署

这些步骤针对具有上游Backstage发行版的vanilla OpenShift容器平台集群进行了验证。如果您启用了任何特定于Red Hat Developer Hub的功能，请记录一个回退，使插件在vanilla集群上保持功能。

部署Backstage本身？ 查看综合部署指南（Deployment.md）有关将上游Backstage部署到OpenShift的说明，包括OpenShift安全上下文约束所需的Dockerfile补丁。

身份验证和授权？ 请参阅身份验证指南（Authentication.md）有关身份验证流程、CSRF保护、nginx标头转发和身份验证问题疑难解答的详细信息。

实体验证：MCP实体API依赖Backstage的目录验证（允许，允许附加属性）。删除了自定义严格验证，以保持Backstage的香草风格。看验证方法.md 详情及认证-第五次总结.md 为理据。

YAML实体支持：MCP实体API支持通过合并方法从YAML文件加载的实体：目录提供实体定义（真相来源），数据库存储运行时状态（禁用标志），API层在GET上合并它们。这允许运行时状态持续存在，而无需修改Backstage核心。看 MERGE-ARCHITECTURE.md 了解架构细节和 YAML-ENTITY-FIX.md 对于修复历史。

一个命令部署（推荐）

使用统一的构建推送部署脚本来实现完整的部署管道：

# Full pipeline: build, push to registry, deploy to OpenShift, run sanity tests
./build-push-deploy-test.sh

# Target specific components:
./build-push-deploy-test.sh --console-only   # Build/push/deploy console plugin only (default)
./build-push-deploy-test.sh --backstage-only # Build/push/deploy backstage only

# Common options:
./build-push-deploy-test.sh --skip-build    # Skip build (use existing image)
./build-push-deploy-test.sh --build-only    # Build only (don't push or deploy)
./build-push-deploy-test.sh --skip-tests    # Skip sanity tests
./build-push-deploy-test.sh --verbose       # Show detailed output

配置您的环境 通过创造 .image-config.sh:

IMAGE_REGISTRY="quay.io"
IMAGE_ORG="your-org"
CONSOLE_IMAGE_NAME="mcp-tools-catalog"
BACKSTAGE_IMAGE_NAME="backstage"
IMAGE_TAG="latest"
OPENSHIFT_NAMESPACE="mcp-tools-catalog"
DEPLOYMENT_NAME="mcp-catalog"
BACKSTAGE_NAMESPACE="backstage"
BACKSTAGE_DEPLOYMENT_NAME="backstage"

或者使用环境变量：

IMAGE_REGISTRY="quay.io"
IMAGE_ORG="your-org"
IMAGE_NAME="mcp-tools-catalog"
IMAGE_TAG="latest"
OPENSHIFT_NAMESPACE="mcp-tools-catalog"
DEPLOYMENT_NAME="mcp-catalog"
BACKSTAGE_NAMESPACE="backstage"

手动部署步骤

如果您更喜欢手动控制每一步：

构建和推送容器：

docker build -t registry.example.com/mcp-tools-catalog:latest .
docker push registry.example.com/mcp-tools-catalog:latest

使用Helm部署：

helm install mcp-catalog charts/mcp-tools-catalog/ \
  --set image.repository=registry.example.com/mcp-tools-catalog \
  --set image.tag=latest \
  --set openshift.enabled=true

配置环境：

# app-config.production.yaml
mcpCatalog:
  integrations:
    openshift:
      enabled: true
      baseUrl: ${OPENSHIFT_API_URL}
      namespace: mcp-tools

环境变量

# Required
OPENSHIFT_API_URL=https://api.openshift.example.com
OPENSHIFT_NAMESPACE=mcp-tools
OPENSHIFT_TOKEN=${OPENSHIFT_SERVICE_ACCOUNT_TOKEN}

# Optional
MCP_REGISTRY_API_KEY=${MCP_REGISTRY_API_KEY}

📚 文档

插件自述：详细的插件文档
快速入门指南：分步使用示例
数据模型：实体模式和关系
API合同：OpenAPI规范
实施计划：技术架构
功能定义：用户故事和要求

🎯 路线图

✅ 第一阶段：设置和基础

[x] 项目初始化和基本结构
[x] MCP实体的TypeScript模型
[x] 核心服务（目录、搜索、验证）
[x] 共享组件（分页、离线指示器）

✅ 第2阶段：浏览MCP服务器（用户故事1）

[x] 浏览和发现MCP服务器
[x] 包含元数据的服务器详细信息页面
[x] 服务器页面上的工具列表，带有可点击的链接
[x] 基本搜索和过滤
[x] 性能监控

✅ 第三阶段：探索MCP工具（用户故事2）

[x] 浏览具有服务器关系的MCP工具
[x] 带有参数模式的工具详细信息页面
[x] 工具到服务器导航（关系的子组件/部分）
[x] “使用人”工作负载部分
[x] 分层命名（服务器/工具格式）
[x] 验证损坏的服务器引用

✅ 第4阶段：管理MCP工作量（用户故事3）

[x] 使用工具依赖关系浏览MCP工作负载
[x] 包含部署信息的工作负载详细信息页面
[x] 按服务器分组的工具（可扩展部分）
[x] 依赖树视图（分层可视化）
[x] 按工具筛选工作负载
[x] 破损刀具参考的验证

✅ 第五阶段：GitHub目录集成（用户故事4）

[x] GitHub存储库配置文档
[x] 分支和PAT设置说明
[x] 真相来源行为（GitHub覆盖Backstage）
[x] 自动同步和重试机制

🔄 第6阶段：波兰和生产准备

[x] 加载状态和错误边界
[x] 面包屑导航
[x] 具有URL持久性的全局搜索
[x] 实体型滤波芯片
[x] 工作负载详细信息中的可折叠服务器部分
[x] 辅助功能改进（ARIA标签、键盘导航）
[x] ServersTab、searchService、validationService的单元测试
[]剩余组件的单元测试
[]集成测试（Cypress）

🔮 未来的增强功能

[]实时MCP服务器健康监测
[]自动发现MCP服务器
[]高级依赖关系可视化
[]工作流编排集成
[]性能指标和分析

📝 TODO

身份验证支持

当前状态：OpenShift控制台插件通过控制台的内置代理与Backstage目录API通信。目前，Backstage后端已使用禁用身份验证 dangerouslyDisableDefaultAuthPolicy: true 在 app-config.production.yaml这是一个 开发/测试变通方法 并且是 不适合生产.

需要实施什么:

服务到服务身份验证：配置一个静态令牌或服务帐户，控制台插件代理可以使用它与Backstage后端进行身份验证。
代理配置中的令牌注入：更新Helm图表 ConsolePlugin 代理配置包括 Authorization 带有承载令牌的标头。
后台后端令牌验证：配置Backstage以接受和验证目录API请求的服务令牌。

可能的方法:

静态后端令牌：生成 BACKEND_SECRET 在Backstage中，配置控制台插件代理以将其作为承载令牌发送。
Kubernetes服务帐户：将OpenShift的内置服务帐户令牌与Backstage的Kubernetes身份验证提供者一起使用。
OAuth/OIDC集成：与OpenShift的OAuth服务器集成，用于基于用户的身份验证（更复杂，支持每个用户的权限）。

参考文献:

🤝 贡献

分叉存储库
创建特征分支： git checkout -b feature/your-feature
跟随我们的编码标准和添加测试
跑林： yarn lint
提交 pull请求

编码标准

TypeScript第一个 tsconfig.json 强制执行 strict: true （没有新的JavaScript入口点）；使用 npx tsc --noEmit 根和 npx tsc --noEmit -p tsconfig.check.json 内部 plugins/mcp-tools-catalog
ESLint+格式化预处理
Jest用于单元测试
Cypress用于集成测试
Python自动化/工具必须包含类型提示和传递 mypy --strict
插件开发的后台约定

🔧 故障排除

常见问题

问题	解决方案
实体未出现	检查YAML语法，验证实体处理器注册
断开关系	验证EntityRef格式，确保目标实体存在
插件未加载	验证App.tsx中的导入，检查浏览器控制台
API错误	检查身份验证，验证请求格式

调试模式

# Enable debug logging
backend:
  logger:
    level: debug

使用说明

MCP工具目录

🎯 项目概述

✨ 特性

🧭 宪法对齐

🏗️ 建筑

📚 文档

🚀 快速开始

先决条件

安装

注册您的第一台MCP服务器

📁 项目结构

🧪 开发与测试

本地开发

测试

手动测试场景

🏭 部署

Vanilla OpenShift部署

一个命令部署（推荐）

手动部署步骤

环境变量

📚 文档

🎯 路线图

✅ 第一阶段：设置和基础

✅ 第2阶段：浏览MCP服务器（用户故事1）

✅ 第三阶段：探索MCP工具（用户故事2）

✅ 第4阶段：管理MCP工作量（用户故事3）

✅ 第五阶段：GitHub目录集成（用户故事4）

🔄 第6阶段：波兰和生产准备

🔮 未来的增强功能

📝 TODO

身份验证支持

🤝 贡献

编码标准

🔧 故障排除

常见问题

调试模式

支持资源

📄 许可证

🙏 致谢

相关 MCP

架构图生成服务

MCP搜索管理扩展

多云基础设施图生成服务

统一MCP服务器

MCP服务器管理工具

AI资产中心插件