[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-IBM--mcp-context-forge":3,"tool-IBM--mcp-context-forge":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",142651,2,"2026-04-06T23:34:12",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":117,"forks":118,"last_commit_at":119,"license":120,"difficulty_score":10,"env_os":121,"env_gpu":122,"env_ram":122,"env_deps":123,"category_tags":130,"github_topics":131,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":152,"updated_at":153,"faqs":154,"releases":170},4897,"IBM\u002Fmcp-context-forge","mcp-context-forge","An AI Gateway, registry, and proxy that sits in front of any MCP, A2A, or REST\u002FgRPC APIs, exposing a unified endpoint with centralized discovery, guardrails and management. Optimizes Agent & Tool calling, and supports plugins.","ContextForge 是一款由 IBM 开源的 AI 网关与注册中心，旨在为复杂的 AI 基础设施提供统一的管理入口。在当前的开发环境中，AI 代理往往需要调用分散的工具、MCP 服务以及各类 REST 或 gRPC 接口，导致连接配置繁琐且难以监控。ContextForge 通过将这些异构资源联邦到一个干净的端点，有效解决了服务发现困难、权限管理分散以及调用链路不透明等痛点。\n\n这款工具特别适合 AI 应用开发者、系统架构师以及需要构建多代理协作系统的技术团队使用。它不仅能作为标准的 MCP 服务器运行，还支持通过插件扩展功能，内置了速率限制、身份认证、自动重试等企业级治理特性。其独特的技术亮点在于强大的协议转换能力，能够无缝桥接 MCP、A2A 协议与传统 API，并原生支持 OpenTelemetry 可观测性，方便对接 Phoenix、Jaeger 等追踪后端。此外，ContextForge 具备优秀的扩展性，支持基于 Redis 的多集群联邦与缓存机制，可轻松部署于 Kubernetes 环境，帮助开发者高效构建稳定、可控的 AI 应用生态。","# ContextForge\n\n> An open source registry and proxy that federates MCP, A2A, and REST\u002FgRPC APIs with centralized governance, discovery, and observability. Optimizes Agent & Tool calling, and supports plugins.\n\n![ContextForge Banner](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_a4a132298bba.png)\n\n\u003C!-- === CI \u002F Security \u002F Build Badges === -->\n[![Build Python Package](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpython-package.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpython-package.yml) \n[![Bandit Security](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fbandit.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fbandit.yml) \n[![Dependency Review](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fdependency-review.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fdependency-review.yml) \n[![Tests & Coverage](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpytest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpytest.yml) \n[![Lint & Static Analysis](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Flint.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Flint.yml)\n\n\u003C!-- === Package \u002F Container === -->\n[![Async](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fasync-await-green.svg)](https:\u002F\u002Fdocs.python.org\u002F3\u002Flibrary\u002Fasyncio.html)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fibm\u002Fmcp-context-forge)](LICENSE) \n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-contextforge-gateway)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-contextforge-gateway\u002F) \n[![Docker Image](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocker-ghcr.io%2Fibm%2Fmcp--context--forge-blue)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fpkgs\u002Fcontainer\u002Fmcp-context-forge) \n\n\n**ContextForge** is an open source registry and proxy that federates tools, agents, and APIs into one clean endpoint for your AI clients. It provides centralized governance, discovery, and observability across your AI infrastructure:\n\n- **Tools Gateway** — MCP, REST, gRPC-to-MCP translation, and TOON compression\n- **Agent Gateway** — A2A protocol, OpenAI-compatible and Anthropic agent routing\n- **API Gateway** — Rate limiting, auth, retries, and reverse proxy for REST services\n- **Plugin Extensibility** — 40+ plugins for additional transports, protocols, and integrations\n- **Observability** — OpenTelemetry tracing with Phoenix, Jaeger, Zipkin, and other OTLP backends\n\nIt runs as a fully compliant MCP server, deployable via PyPI or Docker, and scales to multi-cluster environments on Kubernetes with Redis-backed federation and caching.\n\n![ContextForge](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_3ca8dee71d38.gif)\n---\n\n\u003C!-- vscode-markdown-toc -->\n## Table of Contents\n\n- [Overview & Goals](#overview--goals)\n- [Quick Start - PyPI](#quick-start---pypi)\n- [Quick Start - Containers](#quick-start---containers)\n- [VS Code Dev Container](#quick-start-vs-code-dev-container)\n- [Installation](#installation)\n- [Upgrading](#upgrading)\n- [Configuration](#configuration)\n- [Running](#running)\n- [Cloud Deployment](#cloud-deployment)\n- [API Reference](#api-reference)\n- [Testing](#testing)\n- [Project Structure](#project-structure)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n\n---\n\n### 📌 Quick Links\n\n| Resource | Description |\n|----------|-------------|\n| **[5-Minute Setup](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2503)** | Get started fast — uvx, Docker, Compose, or local dev |\n| **[Getting Help](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2504)** | Support options, FAQ, community channels |\n| **[Issue Guide](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2502)** | How to file bugs, request features, contribute |\n| **[Full Documentation](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F)** | Complete guides, tutorials, API reference |\n\n---\n\n## Overview & Goals\n\n**ContextForge** is an open source registry and proxy that federates any [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io) (MCP) server, A2A server, or REST\u002FgRPC API, providing centralized governance, discovery, and observability. It optimizes agent and tool calling, and supports plugins. See the [project roadmap](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F) for more details.\n\nIt currently supports:\n\n* Federation across multiple MCP and REST services\n* **A2A (Agent-to-Agent) integration** for external AI agents (OpenAI, Anthropic, custom)\n* **gRPC-to-MCP translation** via automatic reflection-based service discovery\n* Virtualization of legacy APIs as MCP-compliant tools and servers\n* Transport over HTTP, JSON-RPC, WebSocket, SSE (with configurable keepalive), stdio and streamable-HTTP\n* An Admin UI for real-time management, configuration, and log monitoring (with airgapped deployment support)\n* Built-in auth, retries, and rate-limiting with user-scoped OAuth tokens and unconditional X-Upstream-Authorization header support\n* **OpenTelemetry observability** with Phoenix, Jaeger, Zipkin, and other OTLP backends\n* Scalable deployments via Docker or PyPI, Redis-backed caching, and multi-cluster federation\n\n![ContextForge Architecture](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fimages\u002Fmcpgateway.svg)\n\nFor a list of upcoming features, check out the [ContextForge Roadmap](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F)\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔌 Gateway Layer with Protocol Flexibility\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* Federates any MCP server or REST API\n* Lets you choose your MCP protocol version (e.g., `2025-11-25`)\n* Exposes a single, unified interface for diverse backends\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🧩 Virtualization of REST\u002FgRPC Services\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* Wraps non-MCP services as virtual MCP servers\n* Registers tools, prompts, and resources with minimal configuration\n* **gRPC-to-MCP translation** via server reflection protocol\n* Automatic service discovery and method introspection\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔁 REST-to-MCP Tool Adapter\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* Adapts REST APIs into tools with:\n\n  * Automatic JSON Schema extraction\n  * Support for headers, tokens, and custom auth\n  * Retry, timeout, and rate-limit policies\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🧠 Unified Registries\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **Prompts**: Jinja2 templates, multimodal support, rollback\u002Fversioning\n* **Resources**: URI-based access, MIME detection, caching, SSE updates\n* **Tools**: Native or adapted, with input validation and concurrency controls\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📈 Admin UI, Observability & Dev Experience\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* Admin UI built with HTMX + Alpine.js\n* Real-time log viewer with filtering, search, and export capabilities\n* Auth: Basic, JWT, or custom schemes\n* Structured logs, health endpoints, metrics\n* 7,000+ tests, Makefile targets, live reload, pre-commit hooks\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔍 OpenTelemetry Observability\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **Vendor-agnostic tracing** with OpenTelemetry (OTLP) protocol support\n* **Multiple backend support**: Phoenix (LLM-focused), Jaeger, Zipkin, Tempo, DataDog, New Relic\n* **Distributed tracing** across federated gateways and services\n* **Automatic instrumentation** of tools, prompts, resources, and gateway operations\n* **LLM-specific metrics**: Token usage, costs, model performance\n* **Zero-overhead when disabled** with graceful degradation\n\nSee **[Observability Documentation](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fobservability\u002F)** for setup guides with Phoenix, Jaeger, and other backends.\n\n\u003C\u002Fdetails>\n\n---\n\n## Quick Start - PyPI\n\nContextForge is published on [PyPI](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-contextforge-gateway\u002F) as `mcp-contextforge-gateway`.\n\n---\n\n**TLDR;**:\n(single command using [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F))\n\n```bash\n# Quick start with environment variables\nBASIC_AUTH_PASSWORD=pass \\\nMCPGATEWAY_UI_ENABLED=true \\\nMCPGATEWAY_ADMIN_API_ENABLED=true \\\nPLATFORM_ADMIN_EMAIL=admin@example.com \\\nPLATFORM_ADMIN_PASSWORD=changeme \\\nPLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\" \\\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n\n# Or better: use the provided .env.example\ncp .env.example .env\n# Edit .env to customize your settings\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📋 Prerequisites\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **Python ≥ 3.11**\n* **curl + jq** - only for the last smoke-test step\n\n\u003C\u002Fdetails>\n\n### 1 - Install & run (copy-paste friendly)\n\n```bash\n# 1️⃣  Isolated env + install from pypi\nmkdir mcpgateway && cd mcpgateway\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install --upgrade pip\npip install mcp-contextforge-gateway\n\n# 2️⃣  Copy and customize the configuration\n# Download the example environment file\ncurl -O https:\u002F\u002Fraw.githubusercontent.com\u002FIBM\u002Fmcp-context-forge\u002Fmain\u002F.env.example\ncp .env.example .env\n# Edit .env to customize your settings (especially passwords!)\n\n# Or set environment variables directly:\nexport MCPGATEWAY_UI_ENABLED=true\nexport MCPGATEWAY_ADMIN_API_ENABLED=true\nexport PLATFORM_ADMIN_EMAIL=admin@example.com\nexport PLATFORM_ADMIN_PASSWORD=changeme\nexport PLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\"\n\nBASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  mcpgateway --host 0.0.0.0 --port 4444 &   # admin\u002Fpass\n\n# 3️⃣  Generate a bearer token & smoke-test the API\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\n\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002F127.0.0.1:4444\u002Fversion | jq\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Windows (PowerShell) quick-start\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```powershell\n# 1️⃣  Isolated env + install from PyPI\nmkdir mcpgateway ; cd mcpgateway\npython3 -m venv .venv ; .\\.venv\\Scripts\\Activate.ps1\npip install --upgrade pip\npip install mcp-contextforge-gateway\n\n# 2️⃣  Copy and customize the configuration\n# Download the example environment file\nInvoke-WebRequest -Uri \"https:\u002F\u002Fraw.githubusercontent.com\u002FIBM\u002Fmcp-context-forge\u002Fmain\u002F.env.example\" -OutFile \".env.example\"\nCopy-Item .env.example .env\n# Edit .env to customize your settings\n\n# Or set environment variables (session-only)\n$Env:MCPGATEWAY_UI_ENABLED        = \"true\"\n$Env:MCPGATEWAY_ADMIN_API_ENABLED = \"true\"\n# Note: Basic auth for API is disabled by default (API_ALLOW_BASIC_AUTH=false)\n$Env:JWT_SECRET_KEY               = \"my-test-key-but-now-longer-than-32-bytes\"\n$Env:PLATFORM_ADMIN_EMAIL         = \"admin@example.com\"\n$Env:PLATFORM_ADMIN_PASSWORD      = \"changeme\"\n$Env:PLATFORM_ADMIN_FULL_NAME     = \"Platform Administrator\"\n\n# 3️⃣  Launch the gateway\nmcpgateway.exe --host 0.0.0.0 --port 4444\n\n#   Optional: background it\n# Start-Process -FilePath \"mcpgateway.exe\" -ArgumentList \"--host 0.0.0.0 --port 4444\"\n\n# 4️⃣  Bearer token and smoke-test\n$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `\n    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n\ncurl -s -H \"Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN\" `\n     http:\u002F\u002F127.0.0.1:4444\u002Fversion | jq\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>⚡ Alternative: uv (faster)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```powershell\n# 1️⃣  Isolated env + install from PyPI using uv\nmkdir mcpgateway ; cd mcpgateway\nuv venv\n.\\.venv\\Scripts\\activate\nuv pip install mcp-contextforge-gateway\n\n# Continue with steps 2️⃣-4️⃣ above...\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>More configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nCopy [.env.example](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002F.env.example) to `.env` and tweak any of the settings (or use them as env variables).\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🚀 End-to-end demo (register a local MCP server)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# 1️⃣  Spin up the sample GO MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)\npython3 -m mcpgateway.translate \\\n     --stdio \"docker run --rm -i ghcr.io\u002Fibm\u002Ffast-time-server:latest -transport=stdio\" \\\n     --expose-sse \\\n     --port 8003\n\n# Or using the official mcp-server-git using uvx:\npip install uv # to install uvx, if not already installed\npython3 -m mcpgateway.translate --stdio \"uvx mcp-server-git\" --expose-sse --port 9000\n\n# Alternative: running the local binary\n# cd mcp-servers\u002Fgo\u002Ffast-time-server; make build\n# python3 -m mcpgateway.translate --stdio \".\u002Fdist\u002Ffast-time-server -transport=stdio\" --expose-sse --port 8002\n\n# NEW: Expose via multiple protocols simultaneously!\npython3 -m mcpgateway.translate \\\n     --stdio \"uvx mcp-server-git\" \\\n     --expose-sse \\\n     --expose-streamable-http \\\n     --port 9000\n# Now accessible via both \u002Fsse (SSE) and \u002Fmcp (streamable HTTP) endpoints\n\n# 2️⃣  Register it with the gateway\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -d '{\"name\":\"fast_time\",\"url\":\"http:\u002F\u002Flocalhost:8003\u002Fsse\"}' \\\n     http:\u002F\u002Flocalhost:4444\u002Fgateways\n\n# 3️⃣  Verify tool catalog\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" http:\u002F\u002Flocalhost:4444\u002Ftools | jq\n\n# 4️⃣  Create a *virtual server* bundling those tools. Use the ID of tools from the tool catalog (Step #3) and pass them in the associatedTools list.\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -d '{\"server\":{\"name\":\"time_server\",\"description\":\"Fast time tools\",\"associated_tools\":[\u003CID_OF_TOOLS>]}}' \\\n     http:\u002F\u002Flocalhost:4444\u002Fservers | jq\n\n# Example curl\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\"\n     -H \"Content-Type: application\u002Fjson\"\n     -d '{\"server\":{\"name\":\"time_server\",\"description\":\"Fast time tools\",\"associated_tools\":[\"6018ca46d32a4ac6b4c054c13a1726a2\"]}}' \\\n     http:\u002F\u002Flocalhost:4444\u002Fservers | jq\n\n# 5️⃣  List servers (should now include the UUID of the newly created virtual server)\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" http:\u002F\u002Flocalhost:4444\u002Fservers | jq\n\n# 6️⃣  Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)\nnpx -y @modelcontextprotocol\u002Finspector\n# Transport Type: Streamable HTTP, URL: http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp,  Header Name: \"Authorization\", Bearer Token\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🖧 Using the stdio wrapper (mcpgateway-wrapper)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nexport MCP_SERVER_URL=http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp\npython3 -m mcpgateway.wrapper  # Ctrl-C to exit\n```\n\nYou can also run it with `uv` or inside Docker\u002FPodman - see the *Containers* section above.\n\nIn MCP Inspector, define `MCP_AUTH` and `MCP_SERVER_URL` env variables, and select `python3` as the Command, and `-m mcpgateway.wrapper` as Arguments.\n\n```bash\necho $PWD\u002F.venv\u002Fbin\u002Fpython3 # Using the Python3 full path ensures you have a working venv\nexport MCP_SERVER_URL='http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp'\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nnpx -y @modelcontextprotocol\u002Finspector\n```\n\nor\n\nPass the url and auth as arguments (no need to set environment variables)\n```bash\nnpx -y @modelcontextprotocol\u002Finspector\ncommand as `python`\nArguments as `-m mcpgateway.wrapper --url \"http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp\" --auth \"Bearer \u003Cyour token>\"`\n```\n\n\nWhen using a MCP Client such as Claude with stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpgateway-wrapper\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcpgateway.wrapper\"],\n      \"env\": {\n        \"MCP_AUTH\": \"Bearer your-token-here\",\n        \"MCP_SERVER_URL\": \"http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\",\n        \"MCP_TOOL_CALL_TIMEOUT\": \"120\"\n      }\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## Quick Start - Containers\n\nUse the official OCI image from GHCR with **Docker** *or* **Podman**.\nPlease note: Currently, arm64 is not supported on production. If you are e.g. running on MacOS with Apple Silicon chips (M1, M2, etc), you can run the containers using Rosetta or install via PyPi instead.\n\n### 🚀 Quick Start - Docker Compose\n\nGet a full stack running with PostgreSQL and Redis in under 30 seconds:\n\n```bash\n# Clone and start the stack\ngit clone https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge.git\ncd mcp-context-forge\n\n# Start with PostgreSQL (recommended for production)\ndocker compose up -d\n\n# Check status\ndocker compose ps\n\n# View logs\ndocker compose logs -f gateway\n\n# Access Admin UI: http:\u002F\u002Flocalhost:8080\u002Fadmin (login with PLATFORM_ADMIN_EMAIL\u002FPASSWORD)\n# Generate API token\ndocker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n```\n\n**What you get:**\n- 🗄️ **PostgreSQL** - Production-ready database with 55+ tables\n- 🚀 **ContextForge** - Full-featured gateway with Admin UI\n- 📊 **Redis** - High-performance caching and session storage\n- 🔧 **Admin Tools** - pgAdmin, Redis Insight for database management\n- 🌐 **Nginx Proxy** - Caching reverse proxy on port 8080\n\n**Enable HTTPS (optional):**\n```bash\n# Start with TLS enabled (auto-generates self-signed certs)\nmake compose-tls\n\n# Access via HTTPS: https:\u002F\u002Flocalhost:8443\u002Fadmin\n\n# Or bring your own certificates:\n# Unencrypted key:\nmkdir -p certs\ncp your-cert.pem certs\u002Fcert.pem && cp your-key.pem certs\u002Fkey.pem\nmake compose-tls\n\n# Passphrase-protected key:\nmkdir -p certs\ncp your-cert.pem certs\u002Fcert.pem && cp your-encrypted-key.pem certs\u002Fkey-encrypted.pem\necho \"KEY_FILE_PASSWORD=your-passphrase\" >> .env\nmake compose-tls\n```\n\n### ☸️ Quick Start - Helm (Kubernetes)\n\nDeploy to Kubernetes with enterprise-grade features:\n\n```bash\n# Add Helm repository (when available)\n# helm repo add mcp-context-forge https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\n# helm repo update\n\n# For now, use local chart\ngit clone https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge.git\ncd mcp-context-forge\u002Fcharts\u002Fmcp-stack\n\n# Install with PostgreSQL (default)\nhelm install mcp-gateway . \\\n  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \\\n  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \\\n  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key\n\n# Check deployment status\nkubectl get pods -l app.kubernetes.io\u002Fname=mcp-context-forge\n\n# Port forward to access Admin UI\nkubectl port-forward svc\u002Fmcp-gateway-mcp-context-forge 4444:80\n# Access: http:\u002F\u002Flocalhost:4444\u002Fadmin\n\n# Generate API token\nkubectl exec deployment\u002Fmcp-gateway-mcp-context-forge -- \\\n  python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@yourcompany.com --exp 10080 --secret your-secret-key\n```\n\n> SSRF note: Helm defaults to strict SSRF settings (`SSRF_ALLOW_PRIVATE_NETWORKS=false`).\n> If you register in-cluster tool URLs (for example fast-time or fast-test services),\n> allow only your cluster CIDRs via `mcpContextForge.config.SSRF_ALLOWED_NETWORKS` or,\n> for local-only benchmark setups, temporarily set `SSRF_ALLOW_PRIVATE_NETWORKS=true`.\n> See `docs\u002Fdocs\u002Fmanage\u002Fconfiguration.md#ssrf-protection` and `docs\u002Fdocs\u002Fdeployment\u002Fhelm.md`.\n\n**Enterprise Features:**\n- 🔄 **Auto-scaling** - HPA with CPU\u002Fmemory targets\n- 🗄️ **Database Choice** - PostgreSQL (prod), SQLite (dev)\n- 📊 **Observability** - Prometheus metrics, OpenTelemetry tracing\n- 🔒 **Security** - RBAC, network policies, secret management\n- 🚀 **High Availability** - Multi-replica deployments with Redis clustering\n- 📈 **Monitoring** - Built-in Grafana dashboards and alerting\n\n---\n\n### 🐳 Docker (Single Container)\n\n```bash\ndocker run -d --name mcpgateway \\\n  -p 4444:4444 \\\n  -e MCPGATEWAY_UI_ENABLED=true \\\n  -e MCPGATEWAY_ADMIN_API_ENABLED=true \\\n  -e HOST=0.0.0.0 \\\n  -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  -e AUTH_REQUIRED=true \\\n  -e PLATFORM_ADMIN_EMAIL=admin@example.com \\\n  -e PLATFORM_ADMIN_PASSWORD=changeme \\\n  -e PLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\" \\\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F.\u002Fmcp.db \\\n  -e SECURE_COOKIES=false \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n\n# Tail logs and generate API key\ndocker logs -f mcpgateway\ndocker run --rm -it ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2 \\\n  python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n```\n\nBrowse to **[http:\u002F\u002Flocalhost:4444\u002Fadmin](http:\u002F\u002Flocalhost:4444\u002Fadmin)** and login with `PLATFORM_ADMIN_EMAIL` \u002F `PLATFORM_ADMIN_PASSWORD`.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Advanced: Persistent storage, host networking, airgapped\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Persist SQLite database:**\n```bash\nmkdir -p $(pwd)\u002Fdata && touch $(pwd)\u002Fdata\u002Fmcp.db && chmod 777 $(pwd)\u002Fdata\ndocker run -d --name mcpgateway --restart unless-stopped \\\n  -p 4444:4444 -v $(pwd)\u002Fdata:\u002Fdata \\\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  -e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \\\n  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=changeme \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n**Host networking** (access local MCP servers):\n```bash\ndocker run -d --name mcpgateway --network=host \\\n  -v $(pwd)\u002Fdata:\u002Fdata -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  -e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n**Airgapped deployment** (no internet):\n```bash\ndocker build -f Containerfile.lite -t mcpgateway:airgapped .\ndocker run -d --name mcpgateway -p 4444:4444 \\\n  -e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \\\n  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  mcpgateway:airgapped\n```\n\n\u003C\u002Fdetails>\n\n---\n\n### 🦭 Podman (rootless-friendly)\n\n```bash\npodman run -d --name mcpgateway \\\n  -p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:\u002F\u002F\u002F.\u002Fmcp.db \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Advanced: Persistent storage, host networking\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Persist SQLite:**\n```bash\nmkdir -p $(pwd)\u002Fdata && chmod 777 $(pwd)\u002Fdata\npodman run -d --name mcpgateway --restart=on-failure \\\n  -p 4444:4444 -v $(pwd)\u002Fdata:\u002Fdata \\\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n**Host networking:**\n```bash\npodman run -d --name mcpgateway --network=host \\\n  -v $(pwd)\u002Fdata:\u002Fdata -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>✏️ Docker\u002FPodman tips\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **.env files** - Put all the `-e FOO=` lines into a file and replace them with `--env-file .env`. See the provided [.env.example](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002F.env.example) for reference.\n* **Pinned tags** - Use an explicit version (e.g. `1.0.0-RC-2`) instead of `latest` for reproducible builds.\n* **JWT tokens** - Generate one in the running container:\n\n  ```bash\n  docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n  ```\n* **Upgrades** - Stop, remove, and rerun with the same `-v $(pwd)\u002Fdata:\u002Fdata` mount; your DB and config stay intact.\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🚑 Smoke-test the running container\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002Flocalhost:4444\u002Fhealth | jq\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002Flocalhost:4444\u002Ftools | jq\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002Flocalhost:4444\u002Fversion | jq\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🖧 Running ContextForge stdio wrapper\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe `mcpgateway.wrapper` lets you connect to the gateway over **stdio** while keeping JWT authentication. You should run this from the MCP Client. The example below is just for testing.\n\n```bash\n# Set environment variables\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nexport MCP_SERVER_URL='http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp'\nexport MCP_TOOL_CALL_TIMEOUT=120\nexport MCP_WRAPPER_LOG_LEVEL=DEBUG  # or OFF to disable logging\n\ndocker run --rm -i \\\n  -e MCP_AUTH=$MCP_AUTH \\\n  -e MCP_SERVER_URL=http:\u002F\u002Fhost.docker.internal:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp \\\n  -e MCP_TOOL_CALL_TIMEOUT=120 \\\n  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2 \\\n  python3 -m mcpgateway.wrapper\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\n## Quick Start: VS Code Dev Container\n\nClone the repo and open in VS Code—it will detect `.devcontainer` and prompt to **\"Reopen in Container\"**. The container includes Python 3.11, Docker CLI, and all project dependencies.\n\nFor detailed setup, workflows, and GitHub Codespaces instructions, see **[Developer Onboarding](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fdeveloper-onboarding\u002F)**.\n\n---\n\n## Installation\n\n```bash\nmake venv install          # create .venv + install deps\nmake serve                 # gunicorn on :4444\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Alternative: UV or pip\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# UV (faster)\nuv venv && source .venv\u002Fbin\u002Factivate\nuv pip install -e '.[dev]'\n\n# pip\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install -e \".[dev]\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>PostgreSQL adapter setup\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nInstall the `psycopg` driver for PostgreSQL:\n\n```bash\n# Install system dependencies first\n# Debian\u002FUbuntu: sudo apt-get install libpq-dev\n# macOS: brew install libpq\n\nuv pip install 'psycopg[binary]'   # dev (pre-built wheels)\n# or: uv pip install 'psycopg[c]'  # production (requires compiler)\n```\n\nConnection URL format:\n```bash\nDATABASE_URL=postgresql+psycopg:\u002F\u002Fuser:password@localhost:5432\u002Fmcp\n```\n\nQuick Postgres container:\n```bash\ndocker run --name mcp-postgres \\\n  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword \\\n  -e POSTGRES_DB=mcp -p 5432:5432 -d postgres\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## Upgrading\n\nFor upgrade instructions, migration guides, and rollback procedures, see:\n\n- **[Upgrade Guide](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fupgrade\u002F)** — General upgrade procedures\n- **[CHANGELOG.md](.\u002FCHANGELOG.md)** — Version history and breaking changes\n- **[MIGRATION-0.7.0.md](.\u002FMIGRATION-0.7.0.md)** — Multi-tenancy migration (v0.6.x → v0.7.x)\n\n---\n\n## Configuration\n\n> ⚠️ If any required `.env` variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.\n\nCopy the provided [.env.example](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002F.env.example) to `.env` and update the security-sensitive values below.\n\n### 🔐 Required: Change Before Use\n\nThese variables have insecure defaults and **must be changed** before production deployment:\n\n| Variable | Description | Default | Action Required |\n|----------|-------------|---------|-----------------|\n| `JWT_SECRET_KEY` | Secret key for signing JWT tokens (32+ chars) | `my-test-key-but-now-longer-than-32-bytes` | Generate with `openssl rand -hex 32` |\n| `AUTH_ENCRYPTION_SECRET` | Passphrase for encrypting stored credentials | `my-test-salt` | Generate with `openssl rand -hex 32` |\n| `BASIC_AUTH_USER` | Username for HTTP Basic auth | `admin` | Change for production |\n| `BASIC_AUTH_PASSWORD` | Password for HTTP Basic auth | `changeme` | Set a strong password |\n| `PLATFORM_ADMIN_EMAIL` | Email for bootstrap admin user | `admin@example.com` | Use real admin email |\n| `PLATFORM_ADMIN_PASSWORD` | Password for bootstrap admin user | `changeme` | Set a strong password |\n| `PLATFORM_ADMIN_FULL_NAME` | Display name for bootstrap admin | `Admin User` | Set admin name |\n\n### 🔒 Security Defaults (Secure by Default)\n\nThese settings are enabled by default for security—only disable for backward compatibility:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `REQUIRE_JTI` | Require JTI claim in tokens for revocation support | `true` |\n| `REQUIRE_TOKEN_EXPIRATION` | Require exp claim in tokens | `true` |\n| `PUBLIC_REGISTRATION_ENABLED` | Allow public user self-registration | `false` |\n\n### 🛡️ Content Security\n\nContent size limits prevent DoS attacks and ensure system stability:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CONTENT_MAX_RESOURCE_SIZE` | Maximum resource content size (bytes) | `102400` (100KB) |\n| `CONTENT_MAX_PROMPT_SIZE` | Maximum prompt template size (bytes) | `10240` (10KB) |\n\n**Note:** Size limits apply only to new create\u002Fupdate operations. Existing content is not retroactively validated.\n\n### ⚙️ Project Defaults (Dev Setup)\n\nThese values differ from code defaults to provide a working local\u002Fdev setup:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HOST` | Bind address | `0.0.0.0` |\n| `MCPGATEWAY_UI_ENABLED` | Enable Admin UI dashboard | `true` |\n| `MCPGATEWAY_ADMIN_API_ENABLED` | Enable Admin API endpoints | `true` |\n| `DATABASE_URL` | SQLAlchemy connection URL | `sqlite:\u002F\u002F\u002F.\u002Fmcp.db` |\n| `SECURE_COOKIES` | Set `false` for HTTP (non-HTTPS) dev | `false` |\n\n### 📚 Full Configuration Reference\n\nFor the complete list of 300+ environment variables organized by category (authentication, caching, SSO, observability, etc.), see the **[Configuration Reference](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fconfiguration\u002F)**.\n\n---\n\n## Running\n\n### Quick Reference\n\n| Command | Server | Port | Database | Use Case |\n|---------|--------|------|----------|----------|\n| `make dev` | Uvicorn | **8000** | SQLite | Development (single instance, auto-reload) |\n| `make serve` | Gunicorn | **4444** | SQLite | Production single-node (multi-worker) |\n| `make serve-ssl` | Gunicorn | **4444** | SQLite | Production single-node with HTTPS |\n| `make compose-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | Full stack (3 replicas, load-balanced) |\n| `make compose-sso` | Docker Compose + Keycloak | **8080 \u002F 8180** | PostgreSQL + Redis | Local SSO testing (Keycloak profile) |\n| `make testing-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | Testing environment |\n\n### Development Server (Uvicorn)\n\n```bash\nmake dev                 # Uvicorn on :8000 with auto-reload and SQLite\n# or\n.\u002Frun.sh --reload --log debug --workers 2\n```\n\n> `run.sh` is a wrapper around `uvicorn` that loads `.env`, supports reload, and passes arguments to the server.\n\nKey flags:\n\n| Flag             | Purpose          | Example            |\n| ---------------- | ---------------- | ------------------ |\n| `-e, --env FILE` | load env-file    | `--env prod.env`   |\n| `-H, --host`     | bind address     | `--host 127.0.0.1` |\n| `-p, --port`     | listen port      | `--port 8080`      |\n| `-w, --workers`  | gunicorn workers | `--workers 4`      |\n| `-r, --reload`   | auto-reload      | `--reload`         |\n\n### Production Server (Gunicorn)\n\n```bash\nmake serve               # Gunicorn on :4444 with multiple workers\nmake serve-ssl           # Gunicorn behind HTTPS on :4444 (uses .\u002Fcerts)\n```\n\n### Docker Compose (Full Stack)\n\n```bash\nmake compose-up          # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080\nmake compose-sso         # Start SSO stack with Keycloak on :8180\nmake sso-test-login      # Run SSO smoke checks (providers + login URL + test users)\nmake compose-logs        # Tail logs from all services\nmake compose-down        # Stop the stack\n```\n\n### Manual (Uvicorn)\n\n```bash\nuvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4\n```\n\n---\n\n## Cloud Deployment\n\nContextForge can be deployed to any major cloud platform:\n\n| Platform | Guide |\n|----------|-------|\n| **AWS** | [ECS\u002FEKS Deployment](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Faws\u002F) |\n| **Azure** | [AKS Deployment](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fazure\u002F) |\n| **Google Cloud** | [Cloud Run](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fgoogle-cloud-run\u002F) |\n| **IBM Cloud** | [Code Engine](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fibm-code-engine\u002F) |\n| **Kubernetes** | [Helm Charts](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fminikube\u002F) |\n| **OpenShift** | [OpenShift Deployment](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fopenshift\u002F) |\n\nFor comprehensive deployment guides, see **[Deployment Documentation](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002F)**.\n\n---\n\n## API Reference\n\nInteractive API documentation is available when the server is running:\n\n- **[Swagger UI](http:\u002F\u002Flocalhost:4444\u002Fdocs)** — Try API calls directly in your browser\n- **[ReDoc](http:\u002F\u002Flocalhost:4444\u002Fredoc)** — Browse the complete endpoint reference\n\n**Quick Authentication:**\n```bash\n# Generate a JWT token\nexport TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\n\n# Test API access\ncurl -H \"Authorization: Bearer $TOKEN\" http:\u002F\u002Flocalhost:4444\u002Fhealth\n```\n\nFor comprehensive curl examples covering all endpoints, see the **[API Usage Guide](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fapi-usage\u002F)**.\n\n---\n\n## Testing\n\n```bash\nmake test            # Run unit tests\nmake lint            # Run all linters\nmake doctest         # Run doctests\nmake coverage        # Generate coverage report\n```\n\nSee [Doctest Coverage Guide](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fdoctest-coverage\u002F) for documentation testing details.\n\n---\n\n## Project Structure\n\n```\nmcpgateway\u002F          # Core FastAPI application\n├── main.py          # Entry point\n├── config.py        # Pydantic Settings configuration\n├── db.py            # SQLAlchemy ORM models\n├── schemas.py       # Pydantic validation schemas\n├── services\u002F        # Business logic layer (50+ services)\n├── routers\u002F         # HTTP endpoint definitions\n├── middleware\u002F      # Cross-cutting concerns\n└── transports\u002F      # SSE, WebSocket, stdio, streamable HTTP\n\ntests\u002F               # Test suite (7,000+ tests)\ndocs\u002Fdocs\u002F           # Full documentation (MkDocs)\ncharts\u002F              # Kubernetes\u002FHelm charts\nplugins\u002F             # Plugin framework and implementations\nmcp-servers\u002F         # Sample\u002Ftest MCP servers (see note below)\n```\n\n> **Note:** The `mcp-servers\u002F` directory contains **unsupported sample and test servers**,\n> most originating from community contributions, provided for demonstration and integration\n> testing purposes only. They generally lack session management, persistent state,\n> multi-tenancy, authentication, and other production concerns. They do not go through\n> the same review, testing, and security rigor as the core ContextForge codebase and\n> **should not be run in production**.\n>\n> **Security:** Never run untrusted MCP servers directly on your local filesystem.\n> Always use a sandbox, container, or microVM (e.g. gVisor, Firecracker) with\n> restricted capabilities. Exercise caution when registering any remote MCP server,\n> including servers from public catalogs — perform your own security evaluation\n> before granting access to your gateway.\n\nFor complete structure, see [CONTRIBUTING.md](.\u002FCONTRIBUTING.md) or run `tree -L 2`.\n\n---\n\n## Development\n\n```bash\nmake dev             # Dev server with auto-reload (:8000)\nmake test            # Run test suite\nmake lint            # Run all linters\nmake coverage        # Generate coverage report\n```\n\nRun `make` to see all available targets.\n\nFor development workflows, see:\n- **[Developer Workstation Setup](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fdeveloper-workstation\u002F)**\n- **[Building & Packaging](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fbuilding\u002F)**\n\n---\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n| Issue | Quick Fix |\n|-------|-----------|\n| SQLite \"disk I\u002FO error\" on macOS | Avoid iCloud-synced directories; use `~\u002Fmcp-context-forge\u002Fdata` |\n| Port 4444 not accessible on WSL2 | Configure WSL integration in Docker Desktop |\n| Gateway exits immediately | Copy `.env.example` to `.env` and configure required vars |\n| `ModuleNotFoundError` | Run `make install-dev` |\n\nFor detailed troubleshooting guides, see **[Troubleshooting Documentation](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Ftroubleshooting\u002F)**.\n\n---\n\n## Contributing\n\n1. Fork the repo, create a feature branch.\n2. Run `make lint` and fix any issues.\n3. Keep `make test` green.\n4. Open a PR with signed commits (`git commit -s`).\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)** for full guidelines and **[Issue Guide #2502](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2502)** for how to file bugs, request features, and find issues to work on.\n\n---\n\n## Changelog\n\nA complete changelog can be found here: [CHANGELOG.md](.\u002FCHANGELOG.md)\n\n## License\n\nLicensed under the **Apache License 2.0** - see [LICENSE](.\u002FLICENSE)\n\n\n## Core Authors and Maintainers\n\n- [Mihai Criveti](https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fcrivetimihai) - Distinguished Engineer, Agentic AI\n\nSpecial thanks to our contributors for helping us improve ContextForge:\n\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fgraphs\u002Fcontributors\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_fedfb6102ea2.png\" alt=\"Contributors to the mcp-context-forge repository\" \u002F>\n\u003C\u002Fa>\n\n## Star History and Project Activity\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_7e0a38db4724.png)](https:\u002F\u002Fwww.star-history.com\u002F#ibm\u002Fmcp-context-forge&Date)\n\n\u003C!-- === Usage Stats === -->\n[![PyPi Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_cc97620d43e2.png)](https:\u002F\u002Fpepy.tech\u002Fproject\u002Fmcp-contextforge-gateway) \n[![Stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fibm\u002Fmcp-context-forge?style=social)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fstargazers) \n[![Forks](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002Fibm\u002Fmcp-context-forge?style=social)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fnetwork\u002Fmembers) \n[![Contributors](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcontributors\u002Fibm\u002Fmcp-context-forge)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fgraphs\u002Fcontributors) \n[![Last Commit](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002Fibm\u002Fmcp-context-forge)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fcommits) \n[![Open Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002Fibm\u002Fmcp-context-forge)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fissues) \n","# ContextForge\n\n> 一个开源注册表和代理，用于联合 MCP、A2A 以及 REST\u002FgRPC API，提供集中式治理、服务发现和可观测性。优化代理与工具调用，并支持插件。\n\n![ContextForge 横幅](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_a4a132298bba.png)\n\n\u003C!-- === CI \u002F 安全 \u002F 构建徽章 === -->\n[![构建 Python 包](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpython-package.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpython-package.yml) \n[![Bandit 安全扫描](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fbandit.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fbandit.yml) \n[![依赖项审查](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fdependency-review.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fdependency-review.yml) \n[![测试与覆盖率](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpytest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Fpytest.yml) \n[![代码风格检查与静态分析](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Flint.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Factions\u002Fworkflows\u002Flint.yml)\n\n\u003C!-- === 软件包 \u002F 容器 === -->\n[![异步支持](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fasync-await-green.svg)](https:\u002F\u002Fdocs.python.org\u002F3\u002Flibrary\u002Fasyncio.html)\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fibm\u002Fmcp-context-forge)](LICENSE) \n[![PyPI 版本](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-contextforge-gateway)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-contextforge-gateway\u002F) \n[![Docker 镜像](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocker-ghcr.io%2Fibm%2Fmcp--context--forge-blue)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fpkgs\u002Fcontainer\u002Fmcp-context-forge) \n\n\n**ContextForge** 是一个开源注册表和代理，可将工具、代理和 API 联合到一个干净的端点，供您的 AI 客户端使用。它为您的 AI 基础设施提供集中式治理、服务发现和可观测性：\n\n- **工具网关** — MCP、REST、gRPC 到 MCP 的转换，以及 TOON 压缩\n- **代理网关** — A2A 协议、兼容 OpenAI 和 Anthropic 的代理路由\n- **API 网关** — 速率限制、认证、重试机制，以及 REST 服务的反向代理\n- **插件扩展性** — 40 多个插件，用于额外的传输方式、协议和集成\n- **可观测性** — 使用 OpenTelemetry 进行追踪，支持 Phoenix、Jaeger、Zipkin 等 OTLP 后端\n\n它作为一个完全符合 MCP 标准的服务器运行，可通过 PyPI 或 Docker 部署，并可在 Kubernetes 上通过 Redis 支持的联邦和缓存机制扩展到多集群环境。\n\n![ContextForge](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_3ca8dee71d38.gif)\n---\n\n\u003C!-- vscode-markdown-toc -->\n## 目录\n\n- [概述与目标](#overview--goals)\n- [快速入门 - PyPI](#quick-start---pypi)\n- [快速入门 - 容器](#quick-start---containers)\n- [VS Code 开发容器](#quick-start-vs-code-dev-container)\n- [安装](#installation)\n- [升级](#upgrading)\n- [配置](#configuration)\n- [运行](#running)\n- [云部署](#cloud-deployment)\n- [API 参考](#api-reference)\n- [测试](#testing)\n- [项目结构](#project-structure)\n- [开发](#development)\n- [故障排除](#troubleshooting)\n- [贡献](#contributing)\n\n---\n\n### 📌 快速链接\n\n| 资源 | 描述 |\n|----------|-------------|\n| **[5 分钟设置](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2503)** | 快速上手 — uvx、Docker、Compose 或本地开发 |\n| **[获取帮助](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2504)** | 支持选项、常见问题解答、社区渠道 |\n| **[问题指南](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2502)** | 如何提交 bug、请求功能或贡献 |\n| **[完整文档](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F)** | 完整指南、教程和 API 参考 |\n\n---\n\n## 概述与目标\n\n**ContextForge** 是一个开源注册表和代理，可联合任何 [模型上下文协议](https:\u002F\u002Fmodelcontextprotocol.io) (MCP) 服务器、A2A 服务器或 REST\u002FgRPC API，提供集中式治理、发现和可观测性。它优化了代理和工具调用，并支持插件。更多详情请参阅[项目路线图](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F)。\n\n目前支持：\n\n* 跨多个 MCP 和 REST 服务的联邦\n* **A2A（代理到代理）集成**，用于外部 AI 代理（OpenAI、Anthropic、自定义）\n* **gRPC 到 MCP 的转换**，通过自动反射式服务发现实现\n* 将遗留 API 虚拟化为符合 MCP 标准的工具和服务器\n* 支持 HTTP、JSON-RPC、WebSocket、SSE（可配置保持连接）、stdio 和可流式传输的 HTTP 等传输方式\n* 管理员 UI，用于实时管理、配置和日志监控（支持气隙部署）\n* 内置身份验证、重试和限流功能，支持用户范围内的 OAuth 令牌以及无条件的 X-Upstream-Authorization 头\n* **OpenTelemetry 可观测性**，支持 Phoenix、Jaeger、Zipkin 等 OTLP 后端\n* 通过 Docker 或 PyPI、基于 Redis 的缓存以及多集群联邦实现可扩展部署\n\n![ContextForge 架构](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fimages\u002Fmcpgateway.svg)\n\n有关即将推出的功能列表，请查看[ContextForge 路线图](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F)。\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔌 具有协议灵活性的网关层\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* 联合任何 MCP 服务器或 REST API\n* 允许您选择 MCP 协议版本（例如 `2025-11-25`）\n* 为不同的后端暴露单一的统一接口\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🧩 REST\u002FgRPC 服务的虚拟化\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* 将非 MCP 服务封装为虚拟 MCP 服务器\n* 以最少的配置注册工具、提示和资源\n* **gRPC 到 MCP 的转换**，通过服务器反射协议实现\n* 自动服务发现和方法内省\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔁 REST 到 MCP 工具适配器\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* 将 REST API 适配为工具，具备以下功能：\n\n  * 自动提取 JSON Schema\n  * 支持头部、令牌和自定义身份验证\n  * 重试、超时和速率限制策略\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🧠 统一注册表\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **提示**：Jinja2 模板、多模态支持、回滚\u002F版本控制\n* **资源**：基于 URI 的访问、MIME 检测、缓存、SSE 更新\n* **工具**：原生或适配的工具，带有输入验证和并发控制\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📈 管理员 UI、可观测性和开发体验\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* 管理员 UI 基于 HTMX + Alpine.js 构建\n* 实时日志查看器，具备过滤、搜索和导出功能\n* 身份验证：基本认证、JWT 或自定义方案\n* 结构化日志、健康端点、指标\n* 7,000 多项测试、Makefile 目标、热重载、pre-commit 钩子\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔍 OpenTelemetry 可观测性\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **供应商无关的跟踪**，支持 OpenTelemetry (OTLP) 协议\n* **多后端支持**：Phoenix（专注于 LLM）、Jaeger、Zipkin、Tempo、DataDog、New Relic\n* **分布式跟踪**，覆盖联合的网关和服务\n* **工具、提示、资源和网关操作的自动 instrumentation**\n* **LLM 特定指标**：令牌使用量、成本、模型性能\n* **禁用时零开销**，并能优雅降级\n\n有关 Phoenix、Jaeger 等后端的设置指南，请参阅**[可观测性文档](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fobservability\u002F)**。\n\n\u003C\u002Fdetails>\n\n---\n\n## 快速入门 - PyPI\n\nContextForge 已在 [PyPI](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-contextforge-gateway\u002F) 上发布，包名为 `mcp-contextforge-gateway`。\n\n---\n\n**简而言之；**：\n（使用 [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) 的单条命令）\n\n```bash\n# 使用环境变量快速启动\nBASIC_AUTH_PASSWORD=pass \\\nMCPGATEWAY_UI_ENABLED=true \\\nMCPGATEWAY_ADMIN_API_ENABLED=true \\\nPLATFORM_ADMIN_EMAIL=admin@example.com \\\nPLATFORM_ADMIN_PASSWORD=changeme \\\nPLATFORM_ADMIN_FULL_NAME=\"平台管理员\" \\\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n\n# 或者更好：使用提供的 .env.example\ncp .env.example .env\n# 编辑 .env 以自定义您的设置\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📋 先决条件\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **Python ≥ 3.11**\n* **curl + jq** - 仅用于最后的冒烟测试步骤\n\n\u003C\u002Fdetails>\n\n### 1 - 安装并运行（可复制粘贴）\n\n```bash\n# 1️⃣ 隔离环境 + 从 PyPI 安装\nmkdir mcpgateway && cd mcpgateway\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install --upgrade pip\npip install mcp-contextforge-gateway\n\n# 2️⃣ 复制并定制配置\n# 下载示例环境文件\ncurl -O https:\u002F\u002Fraw.githubusercontent.com\u002FIBM\u002Fmcp-context-forge\u002Fmain\u002F.env.example\ncp .env.example .env\n# 编辑 .env 以自定义您的设置（尤其是密码！）\n\n# 或直接设置环境变量：\nexport MCPGATEWAY_UI_ENABLED=true\nexport MCPGATEWAY_ADMIN_API_ENABLED=true\nexport PLATFORM_ADMIN_EMAIL=admin@example.com\nexport PLATFORM_ADMIN_PASSWORD=changeme\nexport PLATFORM_ADMIN_FULL_NAME=\"平台管理员\"\n\nBASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  mcpgateway --host 0.0.0.0 --port 4444 &   # admin\u002Fpass\n\n# 3️⃣ 生成 Bearer 令牌并进行 API 冒烟测试\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\n\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002F127.0.0.1:4444\u002Fversion | jq\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Windows (PowerShell) 快速入门\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```powershell\n# 1️⃣ 隔离环境 + 从 PyPI 安装\nmkdir mcpgateway ; cd mcpgateway\npython3 -m venv .venv ; .\\.venv\\Scripts\\Activate.ps1\npip install --upgrade pip\npip install mcp-contextforge-gateway\n\n# 2️⃣ 复制并定制配置\n# 下载示例环境文件\nInvoke-WebRequest -Uri \"https:\u002F\u002Fraw.githubusercontent.com\u002FIBM\u002Fmcp-context-forge\u002Fmain\u002F.env.example\" -OutFile \".env.example\"\nCopy-Item .env.example .env\n# 编辑 .env 以自定义您的设置\n\n# 或设置会话级别的环境变量\n$Env:MCPGATEWAY_UI_ENABLED        = \"true\"\n$Env:MCPGATEWAY_ADMIN_API_ENABLED = \"true\"\n# 注意：API 的基本认证默认是关闭的（API_ALLOW_BASIC_AUTH=false）\n$Env:JWT_SECRET_KEY               = \"my-test-key-but-now-longer-than-32-bytes\"\n$Env:PLATFORM_ADMIN_EMAIL         = \"admin@example.com\"\n$Env:PLATFORM_ADMIN_PASSWORD      = \"changeme\"\n$Env:PLATFORM_ADMIN_FULL_NAME     = \"平台管理员\"\n\n# 3️⃣ 启动网关\nmcpgateway.exe --host 0.0.0.0 --port 4444\n\n#   可选：将其置于后台\n\n# 使用 Start-Process 启动 mcpgateway.exe，并传递参数 --host 0.0.0.0 --port 4444\n\n# 4️⃣ Bearer 令牌与冒烟测试\n$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `\n    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n\ncurl -s -H \"Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN\" `\n     http:\u002F\u002F127.0.0.1:4444\u002Fversion | jq\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>⚡ 替代方案：uv（更快）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```powershell\n# 1️⃣ 隔离环境 + 使用 uv 从 PyPI 安装\nmkdir mcpgateway ; cd mcpgateway\nuv venv\n.\\.venv\\Scripts\\activate\nuv pip install mcp-contextforge-gateway\n\n# 继续执行上述步骤 2️⃣-4️⃣...\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>更多配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n将 [.env.example](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002F.env.example) 复制到 `.env` 文件中，并根据需要调整设置（或直接使用这些设置作为环境变量）。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🚀 端到端演示（注册本地 MCP 服务器）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# 1️⃣ 使用 mcpgateway.translate 和 Docker 启动示例 GO MCP 时间服务器（如需可替换为 podman）\npython3 -m mcpgateway.translate \\\n     --stdio \"docker run --rm -i ghcr.io\u002Fibm\u002Ffast-time-server:latest -transport=stdio\" \\\n     --expose-sse \\\n     --port 8003\n\n# 或者使用官方的 mcp-server-git，通过 uvx：\npip install uv # 如果尚未安装，先安装 uvx\npython3 -m mcpgateway.translate --stdio \"uvx mcp-server-git\" --expose-sse --port 9000\n\n# 另一种方式：运行本地二进制文件\n# cd mcp-servers\u002Fgo\u002Ffast-time-server; make build\n# python3 -m mcpgateway.translate --stdio \".\u002Fdist\u002Ffast-time-server -transport=stdio\" --expose-sse --port 8002\n\n# 新功能：同时支持多种协议！\npython3 -m mcpgateway.translate \\\n     --stdio \"uvx mcp-server-git\" \\\n     --expose-sse \\\n     --expose-streamable-http \\\n     --port 9000\n# 现在可以通过 \u002Fsse（SSE）和 \u002Fmcp（流式 HTTP）两个端点访问\n\n# 2️⃣ 将其注册到网关\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -d '{\"name\":\"fast_time\",\"url\":\"http:\u002F\u002Flocalhost:8003\u002Fsse\"}' \\\n     http:\u002F\u002Flocalhost:4444\u002Fgateways\n\n# 3️⃣ 验证工具目录\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" http:\u002F\u002Flocalhost:4444\u002Ftools | jq\n\n# 4️⃣ 创建一个*虚拟服务器*，将这些工具捆绑在一起。使用工具目录中的工具 ID（步骤 #3），并将其放入 associatedTools 列表中。\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -d '{\"server\":{\"name\":\"time_server\",\"description\":\"快速时间工具\",\"associated_tools\":[\u003C工具ID>]}}' \\\n     http:\u002F\u002Flocalhost:4444\u002Fservers | jq\n\n# 示例 curl 命令\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\"\n     -H \"Content-Type: application\u002Fjson\"\n     -d '{\"server\":{\"name\":\"time_server\",\"description\":\"快速时间工具\",\"associated_tools\":[\"6018ca46d32a4ac6b4c054c13a1726a2\"]}}' \\\n     http:\u002F\u002Flocalhost:4444\u002Fservers | jq\n\n# 5️⃣ 列出服务器（现在应该包含新创建的虚拟服务器的 UUID）\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" http:\u002F\u002Flocalhost:4444\u002Fservers | jq\n\n# 6️⃣ 客户端 HTTP 端口。使用 MCP Inspector CLI 交互式检查（或任何 MCP 客户端）\nnpx -y @modelcontextprotocol\u002Finspector\n# 传输类型：流式 HTTP，URL：http:\u002F\u002Flocalhost:4444\u002Fservers\u002F服务器UUID_1\u002Fmcp，头名称：“Authorization”，Bearer 令牌\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🖧 使用 stdio 包装器（mcpgateway-wrapper）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nexport MCP_SERVER_URL=http:\u002F\u002Flocalhost:4444\u002Fservers\u002F服务器UUID_1\u002Fmcp\npython3 -m mcpgateway.wrapper  # 按 Ctrl-C 退出\n```\n\n你也可以用 `uv` 运行它，或者在 Docker\u002FPodman 中运行——请参阅上面的“容器”部分。\n\n在 MCP Inspector 中，定义 `MCP_AUTH` 和 `MCP_SERVER_URL` 环境变量，选择 `python3` 作为命令，并将 `-m mcpgateway.wrapper` 作为参数。\n\n```bash\necho $PWD\u002F.venv\u002Fbin\u002Fpython3 # 使用 Python3 的完整路径可以确保你有一个可用的虚拟环境\nexport MCP_SERVER_URL='http:\u002F\u002Flocalhost:4444\u002Fservers\u002F服务器UUID_1\u002Fmcp'\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nnpx -y @modelcontextprotocol\u002Finspector\n```\n\n或者\n\n直接将 URL 和认证信息作为参数传递（无需设置环境变量）\n```bash\nnpx -y @modelcontextprotocol\u002Finspector\n命令设为 `python`\n参数设为 `-m mcpgateway.wrapper --url \"http:\u002F\u002Flocalhost:4444\u002Fservers\u002F服务器UUID_1\u002Fmcp\" --auth \"Bearer \u003C你的令牌>\"`\n```\n\n\n当使用像 Claude 这样的具有 stdio 接口的 MCP 客户端时：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpgateway-wrapper\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcpgateway.wrapper\"],\n      \"env\": {\n        \"MCP_AUTH\": \"Bearer 你的令牌\",\n        \"MCP_SERVER_URL\": \"http:\u002F\u002Flocalhost:4444\u002Fservers\u002F服务器UUID_1\",\n        \"MCP_TOOL_CALL_TIMEOUT\": \"120\"\n      }\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 快速入门 - 容器\n\n使用 GHCR 上的官方 OCI 镜像，搭配 **Docker** *或* **Podman**。\n请注意：目前生产环境中不支持 arm64 架构。如果你正在使用搭载 Apple Silicon 芯片的 Mac 设备（如 M1、M2 等），可以使用 Rosetta 运行容器，或者直接通过 PyPI 安装替代方案。\n\n### 🚀 快速入门 - Docker Compose\n\n在不到 30 秒内启动包含 PostgreSQL 和 Redis 的完整堆栈：\n\n```bash\n# 克隆并启动堆栈\ngit clone https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge.git\ncd mcp-context-forge\n\n# 首先启动 PostgreSQL（推荐用于生产环境）\ndocker compose up -d\n\n# 检查状态\ndocker compose ps\n\n# 查看日志\ndocker compose logs -f gateway\n\n# 访问管理界面：http:\u002F\u002Flocalhost:8080\u002Fadmin（使用 PLATFORM_ADMIN_EMAIL\u002FPASSWORD 登录）\n# 生成 API 令牌\ndocker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n```\n\n**你将获得：**\n- 🗄️ **PostgreSQL** - 生产就绪的数据库，包含 55+ 张表\n- 🚀 **ContextForge** - 功能齐全的网关，附带管理界面\n- 📊 **Redis** - 高性能缓存与会话存储\n- 🔧 **管理工具** - pgAdmin、Redis Insight，用于数据库管理\n- 🌐 **Nginx 代理** - 缓存反向代理，运行在 8080 端口\n\n**启用 HTTPS（可选）：**\n```bash\n# 启动时启用 TLS（自动生成自签名证书）\nmake compose-tls\n\n# 通过 HTTPS 访问：https:\u002F\u002Flocalhost:8443\u002Fadmin\n\n# 或者使用你自己的证书：\n# 未加密的密钥：\nmkdir -p certs\ncp 你的-cert.pem certs\u002Fcert.pem && cp 你的-key.pem certs\u002Fkey.pem\nmake compose-tls\n\n# 密码保护的密钥：\nmkdir -p certs\ncp 你的-cert.pem certs\u002Fcert.pem && cp 你的-encrypted-key.pem certs\u002Fkey-encrypted.pem\necho \"KEY_FILE_PASSWORD=你的密码\" >> .env\nmake compose-tls\n```\n\n### ☸️ 快速入门 - Helm（Kubernetes）\n\n部署到 Kubernetes，享受企业级功能：\n\n```bash\n# 添加 Helm 仓库（待上线时）\n\n# 添加 Helm 仓库 mcp-context-forge\n# helm repo add mcp-context-forge https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\n# 更新 Helm 仓库\n# helm repo update\n\n# 目前使用本地 Chart\ngit clone https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge.git\ncd mcp-context-forge\u002Fcharts\u002Fmcp-stack\n\n# 使用 PostgreSQL 安装（默认）\nhelm install mcp-gateway . \\\n  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \\\n  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \\\n  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key\n\n# 检查部署状态\nkubectl get pods -l app.kubernetes.io\u002Fname=mcp-context-forge\n\n# 端口转发以访问管理界面\nkubectl port-forward svc\u002Fmcp-gateway-mcp-context-forge 4444:80\n# 访问地址：http:\u002F\u002Flocalhost:4444\u002Fadmin\n\n# 生成 API 令牌\nkubectl exec deployment\u002Fmcp-gateway-mcp-context-forge -- \\\n  python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@yourcompany.com --exp 10080 --secret your-secret-key\n```\n\n> SSRF 注意：Helm 默认启用严格的 SSRF 设置（`SSRF_ALLOW_PRIVATE_NETWORKS=false`）。\n> 如果您注册集群内工具 URL（例如 fast-time 或 fast-test 服务），请仅通过 `mcpContextForge.config.SSRF_ALLOWED_NETWORKS` 允许您的集群 CIDR，或者对于仅限本地的基准测试设置，临时将 `SSRF_ALLOW_PRIVATE_NETWORKS=true`。\n> 请参阅 `docs\u002Fdocs\u002Fmanage\u002Fconfiguration.md#ssrf-protection` 和 `docs\u002Fdocs\u002Fdeployment\u002Fhelm.md`。\n\n**企业级特性：**\n- 🔄 **自动扩展** - 基于 CPU\u002F内存目标的 HPA\n- 🗄️ **数据库选择** - PostgreSQL（生产环境）、SQLite（开发环境）\n- 📊 **可观测性** - Prometheus 指标、OpenTelemetry 跟踪\n- 🔒 **安全性** - RBAC、网络策略、密钥管理\n- 🚀 **高可用性** - 使用 Redis 集群的多副本部署\n- 📈 **监控** - 内置 Grafana 仪表板和告警\n\n---\n\n### 🐳 Docker（单容器）\n\n```bash\ndocker run -d --name mcpgateway \\\n  -p 4444:4444 \\\n  -e MCPGATEWAY_UI_ENABLED=true \\\n  -e MCPGATEWAY_ADMIN_API_ENABLED=true \\\n  -e HOST=0.0.0.0 \\\n  -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  -e AUTH_REQUIRED=true \\\n  -e PLATFORM_ADMIN_EMAIL=admin@example.com \\\n  -e PLATFORM_ADMIN_PASSWORD=changeme \\\n  -e PLATFORM_ADMIN_FULL_NAME=\"平台管理员\" \\\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F.\u002Fmcp.db \\\n  -e SECURE_COOKIES=false \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n\n# 查看日志并生成 API 密钥\ndocker logs -f mcpgateway\ndocker run --rm -it ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2 \\\n  python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n```\n\n浏览至 **[http:\u002F\u002Flocalhost:4444\u002Fadmin](http:\u002F\u002Flocalhost:4444\u002Fadmin)**，使用 `PLATFORM_ADMIN_EMAIL` \u002F `PLATFORM_ADMIN_PASSWORD` 登录。\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>高级：持久化存储、主机网络、空气隔离\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**持久化 SQLite 数据库：**\n```bash\nmkdir -p $(pwd)\u002Fdata && touch $(pwd)\u002Fdata\u002Fmcp.db && chmod 777 $(pwd)\u002Fdata\ndocker run -d --name mcpgateway --restart unless-stopped \\\n  -p 4444:4444 -v $(pwd)\u002Fdata:\u002Fdata \\\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  -e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \\\n  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=changeme \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n**主机网络**（访问本地 MCP 服务器）：\n```bash\ndocker run -d --name mcpgateway --network=host \\\n  -v $(pwd)\u002Fdata:\u002Fdata -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  -e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n**空气隔离部署**（无互联网）：\n```bash\ndocker build -f Containerfile.lite -t mcpgateway:airgapped .\ndocker run -d --name mcpgateway -p 4444:4444 \\\n  -e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \\\n  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  mcpgateway:airgapped\n```\n\n\u003C\u002Fdetails>\n\n---\n\n### 🦭 Podman（适合无 root 权限用户）\n\n```bash\npodman run -d --name mcpgateway \\\n  -p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:\u002F\u002F\u002F.\u002Fmcp.db \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>高级：持久化存储、主机网络\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**持久化 SQLite：**\n```bash\nmkdir -p $(pwd)\u002Fdata && chmod 777 $(pwd)\u002Fdata\npodman run -d --name mcpgateway --restart=on-failure \\\n  -p 4444:4444 -v $(pwd)\u002Fdata:\u002Fdata \\\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n**主机网络：**\n```bash\npodman run -d --name mcpgateway --network=host \\\n  -v $(pwd)\u002Fdata:\u002Fdata -e DATABASE_URL=sqlite:\u002F\u002F\u002F\u002Fdata\u002Fmcp.db \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>✏️ Docker\u002FPodman 小贴士\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n* **.env 文件** - 将所有 `-e FOO=` 行放入文件中，并用 `--env-file .env` 替代。参考提供的 [.env.example](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002F.env.example)。\n* **固定标签** - 使用明确版本号（如 `1.0.0-RC-2`）而非 `latest`，以确保构建的可重复性。\n* **JWT 令牌** - 在运行中的容器中生成：\n\n  ```bash\n  docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n  ```\n* **升级** - 停止、移除并重新运行，同时保持相同的 `-v $(pwd)\u002Fdata:\u002Fdata` 挂载；您的数据库和配置将保持不变。\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🚑 对运行中的容器进行冒烟测试\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002Flocalhost:4444\u002Fhealth | jq\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002Flocalhost:4444\u002Ftools | jq\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002Flocalhost:4444\u002Fversion | jq\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🖧 运行 ContextForge stdio 包装器\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n`mcpgateway.wrapper` 允许您通过 **stdio** 连接到网关，同时保持 JWT 身份验证。您应在 MCP 客户端上运行此工具。以下示例仅供测试使用。\n\n```bash\n# 设置环境变量\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nexport MCP_SERVER_URL='http:\u002F\u002Flocalhost:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp'\nexport MCP_TOOL_CALL_TIMEOUT=120\nexport MCP_WRAPPER_LOG_LEVEL=DEBUG  # 或 OFF 关闭日志记录\n\ndocker run --rm -i \\\n  -e MCP_AUTH=$MCP_AUTH \\\n  -e MCP_SERVER_URL=http:\u002F\u002Fhost.docker.internal:4444\u002Fservers\u002FUUID_OF_SERVER_1\u002Fmcp \\\n  -e MCP_TOOL_CALL_TIMEOUT=120 \\\n  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \\\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:1.0.0-RC-2 \\\n  python3 -m mcpgateway.wrapper\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 快速入门：VS Code 开发容器\n\n克隆仓库并在 VS Code 中打开——它会检测到 `.devcontainer` 文件并提示选择 **“在容器中重新打开”**。该容器包含 Python 3.11、Docker CLI 以及项目的所有依赖项。\n\n有关详细设置、工作流和 GitHub Codespaces 的说明，请参阅 **[开发者入职指南](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fdeveloper-onboarding\u002F)**。\n\n---\n\n## 安装\n\n```bash\nmake venv install          # 创建 .venv 并安装依赖\nmake serve                 # 使用 gunicorn 在 :4444 端口运行\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>替代方案：UV 或 pip\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# UV（更快）\nuv venv && source .venv\u002Fbin\u002Factivate\nuv pip install -e '.[dev]'\n\n# pip\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install -e \".[dev]\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>PostgreSQL 驱动程序设置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n安装 PostgreSQL 的 `psycopg` 驱动程序：\n\n```bash\n# 先安装系统依赖\n# Debian\u002FUbuntu: sudo apt-get install libpq-dev\n# macOS: brew install libpq\n\nuv pip install 'psycopg[binary]'   # 开发环境（预编译的 wheel 包）\n# 或者：uv pip install 'psycopg[c]'  # 生产环境（需要编译器）\n```\n\n连接 URL 格式如下：\n```bash\nDATABASE_URL=postgresql+psycopg:\u002F\u002Fuser:password@localhost:5432\u002Fmcp\n```\n\n快速启动 Postgres 容器：\n```bash\ndocker run --name mcp-postgres \\\n  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword \\\n  -e POSTGRES_DB=mcp -p 5432:5432 -d postgres\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 升级\n\n有关升级说明、迁移指南和回滚流程，请参阅：\n\n- **[升级指南](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fupgrade\u002F)** — 通用升级流程\n- **[CHANGELOG.md](.\u002FCHANGELOG.md)** — 版本历史及破坏性变更\n- **[MIGRATION-0.7.0.md](.\u002FMIGRATION-0.7.0.md)** — 多租户迁移（v0.6.x → v0.7.x）\n\n---\n\n## 配置\n\n> ⚠️ 如果任何必需的 `.env` 变量缺失或无效，网关将在启动时通过 Pydantic 的验证错误快速失败。\n\n将提供的 [.env.example](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002F.env.example) 复制到 `.env` 文件中，并更新以下安全敏感值。\n\n### 🔐 必须在使用前更改\n\n这些变量具有不安全的默认值，**必须在生产部署前更改**：\n\n| 变量 | 描述 | 默认值 | 是否需要操作 |\n|----------|-------------|---------|-----------------|\n| `JWT_SECRET_KEY` | 用于签名 JWT 令牌的密钥（32 字节以上） | `my-test-key-but-now-longer-than-32-bytes` | 使用 `openssl rand -hex 32` 生成 |\n| `AUTH_ENCRYPTION_SECRET` | 用于加密存储凭据的密码短语 | `my-test-salt` | 使用 `openssl rand -hex 32` 生成 |\n| `BASIC_AUTH_USER` | HTTP Basic 认证的用户名 | `admin` | 生产环境中需更改 |\n| `BASIC_AUTH_PASSWORD` | HTTP Basic 认证的密码 | `changeme` | 设置强密码 |\n| `PLATFORM_ADMIN_EMAIL` | 用于引导管理员用户的邮箱 | `admin@example.com` | 使用真实的管理员邮箱 |\n| `PLATFORM_ADMIN_PASSWORD` | 用于引导管理员用户的密码 | `changeme` | 设置强密码 |\n| `PLATFORM_ADMIN_FULL_NAME` | 引导管理员用户的显示名称 | `Admin User` | 设置管理员姓名 |\n\n### 🔒 安全默认设置（默认安全）\n\n这些设置默认启用以确保安全性——仅在需要向后兼容时才禁用：\n\n| 变量 | 描述 | 默认值 |\n|----------|-------------|---------|\n| `REQUIRE_JTI` | 要求令牌中包含 JTI 声明以支持撤销功能 | `true` |\n| `REQUIRE_TOKEN_EXPIRATION` | 要求令牌中包含 exp 声明 | `true` |\n| `PUBLIC_REGISTRATION_ENABLED` | 允许公众用户自助注册 | `false` |\n\n### 🛡️ 内容安全限制\n\n内容大小限制可防止 DoS 攻击并确保系统稳定性：\n\n| 变量 | 描述 | 默认值 |\n|----------|-------------|---------|\n| `CONTENT_MAX_RESOURCE_SIZE` | 最大资源内容大小（字节） | `102400`（100KB） |\n| `CONTENT_MAX_PROMPT_SIZE` | 最大提示模板大小（字节） | `10240`（10KB） |\n\n**注意**：大小限制仅适用于新的创建或更新操作。现有内容不会被追溯验证。\n\n### ⚙️ 项目默认值（开发环境）\n\n这些值与代码中的默认值不同，旨在提供一个可用的本地\u002F开发环境：\n\n| 变量 | 描述 | 默认值 |\n|----------|-------------|---------|\n| `HOST` | 绑定地址 | `0.0.0.0` |\n| `MCPGATEWAY_UI_ENABLED` | 启用管理界面仪表盘 | `true` |\n| `MCPGATEWAY_ADMIN_API_ENABLED` | 启用管理 API 端点 | `true` |\n| `DATABASE_URL` | SQLAlchemy 连接 URL | `sqlite:\u002F\u002F\u002F.\u002Fmcp.db` |\n| `SECURE_COOKIES` | 对于 HTTP（非 HTTPS）开发环境，设置为 `false` | `false` |\n\n### 📚 完整配置参考\n\n有关按类别（认证、缓存、SSO、可观测性等）组织的 300 多个环境变量的完整列表，请参阅 **[配置参考](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fconfiguration\u002F)**。\n\n---\n\n## 运行\n\n### 快速参考\n\n| 命令 | 服务器 | 端口 | 数据库 | 使用场景 |\n|---------|--------|------|----------|----------|\n| `make dev` | Uvicorn | **8000** | SQLite | 开发环境（单实例，自动重载） |\n| `make serve` | Gunicorn | **4444** | SQLite | 生产环境单节点（多工作进程） |\n| `make serve-ssl` | Gunicorn | **4444** | SQLite | 生产环境单节点，启用 HTTPS |\n| `make compose-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | 全栈部署（3 个副本，负载均衡） |\n| `make compose-sso` | Docker Compose + Keycloak | **8080 \u002F 8180** | PostgreSQL + Redis | 本地 SSO 测试（Keycloak 配置文件） |\n| `make testing-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | 测试环境 |\n\n### 开发服务器（Uvicorn）\n\n```bash\nmake dev                 # Uvicorn 在 :8000 端口运行，支持自动重载和 SQLite\n# 或\n.\u002Frun.sh --reload --log debug --workers 2\n```\n\n> `run.sh` 是一个封装了 `uvicorn` 的脚本，可以加载 `.env` 文件、支持自动重载，并将参数传递给服务器。\n\n关键标志：\n\n| 标志             | 用途          | 示例            |\n| ---------------- | -------------- | ------------------ |\n| `-e, --env FILE` | 加载环境文件    | `--env prod.env`   |\n| `-H, --host`     | 绑定地址        | `--host 127.0.0.1` |\n| `-p, --port`     | 监听端口        | `--port 8080`      |\n| `-w, --workers`  | Gunicorn 工作进程 | `--workers 4`      |\n| `-r, --reload`   | 自动重载        | `--reload`         |\n\n### 生产服务器（Gunicorn）\n\n```bash\nmake serve               # Gunicorn 在 :4444 端口运行，支持多工作进程\nmake serve-ssl           # Gunicorn 后面启用 HTTPS，在 :4444 端口运行（使用 .\u002Fcerts 目录下的证书）\n```\n\n### Docker Compose（全栈部署）\n\n```bash\nmake compose-up          # 启动全栈：PostgreSQL、Redis、3 个网关副本、Nginx 在 :8080 端口运行\nmake compose-sso         # 启动 SSO 栈，Keycloak 在 :8180 端口运行\nmake sso-test-login      # 运行 SSO 功能测试（身份提供商 + 登录 URL + 测试用户）\nmake compose-logs        # 实时查看所有服务的日志\nmake compose-down        # 停止整个栈\n```\n\n### Manual (Uvicorn)\n\n```bash\nuvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4\n```\n\n---\n\n## Cloud Deployment\n\nContextForge can be deployed to any major cloud platform:\n\n| Platform | Guide |\n|----------|-------|\n| **AWS** | [ECS\u002FEKS Deployment](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Faws\u002F) |\n| **Azure** | [AKS Deployment](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fazure\u002F) |\n| **Google Cloud** | [Cloud Run](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fgoogle-cloud-run\u002F) |\n| **IBM Cloud** | [Code Engine](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fibm-code-engine\u002F) |\n| **Kubernetes** | [Helm Charts](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fminikube\u002F) |\n| **OpenShift** | [OpenShift Deployment](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002Fopenshift\u002F) |\n\nFor comprehensive deployment guides, see **[Deployment Documentation](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdeployment\u002F)**.\n\n---\n\n## API Reference\n\nInteractive API documentation is available when the server is running:\n\n- **[Swagger UI](http:\u002F\u002Flocalhost:4444\u002Fdocs)** — Try API calls directly in your browser\n- **[ReDoc](http:\u002F\u002Flocalhost:4444\u002Fredoc)** — Browse the complete endpoint reference\n\n**Quick Authentication:**\n```bash\n# Generate a JWT token\nexport TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\n\n# Test API access\ncurl -H \"Authorization: Bearer $TOKEN\" http:\u002F\u002Flocalhost:4444\u002Fhealth\n```\n\nFor comprehensive curl examples covering all endpoints, see the **[API Usage Guide](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fapi-usage\u002F)**.\n\n---\n\n## Testing\n\n```bash\nmake test            # Run unit tests\nmake lint            # Run all linters\nmake doctest         # Run doctests\nmake coverage        # Generate coverage report\n```\n\nSee [Doctest Coverage Guide](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fdoctest-coverage\u002F) for documentation testing details.\n\n---\n\n## Project Structure\n\n```\nmcpgateway\u002F          # Core FastAPI application\n├── main.py          # Entry point\n├── config.py        # Pydantic Settings configuration\n├── db.py            # SQLAlchemy ORM models\n├── schemas.py       # Pydantic validation schemas\n├── services\u002F        # Business logic layer (50+ services)\n├── routers\u002F         # HTTP endpoint definitions\n├── middleware\u002F      # Cross-cutting concerns\n└── transports\u002F      # SSE, WebSocket, stdio, streamable HTTP\n\ntests\u002F               # Test suite (7,000+ tests)\ndocs\u002Fdocs\u002F           # Full documentation (MkDocs)\ncharts\u002F              # Kubernetes\u002FHelm charts\nplugins\u002F             # Plugin framework and implementations\nmcp-servers\u002F         # Sample\u002Ftest MCP servers (see note below)\n```\n\n> **Note:** The `mcp-servers\u002F` directory contains **unsupported sample and test servers**,\n> most originating from community contributions, provided for demonstration and integration\n> testing purposes only. They generally lack session management, persistent state,\n> multi-tenancy, authentication, and other production concerns. They do not go through\n> the same review, testing, and security rigor as the core ContextForge codebase and\n> **should not be run in production**.\n>\n> **Security:** Never run untrusted MCP servers directly on your local filesystem.\n> Always use a sandbox, container, or microVM (e.g. gVisor, Firecracker) with\n> restricted capabilities. Exercise caution when registering any remote MCP server,\n> including servers from public catalogs — perform your own security evaluation\n> before granting access to your gateway.\n\nFor complete structure, see [CONTRIBUTING.md](.\u002FCONTRIBUTING.md) or run `tree -L 2`.\n\n---\n\n## Development\n\n```bash\nmake dev             # Dev server with auto-reload (:8000)\nmake test            # Run test suite\nmake lint            # Run all linters\nmake coverage        # Generate coverage report\n```\n\nRun `make` to see all available targets.\n\nFor development workflows, see:\n- **[Developer Workstation Setup](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fdeveloper-workstation\u002F)**\n- **[Building & Packaging](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fdevelopment\u002Fbuilding\u002F)**\n\n---\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n| Issue | Quick Fix |\n|-------|-----------|\n| SQLite \"disk I\u002FO error\" on macOS | Avoid iCloud-synced directories; use `~\u002Fmcp-context-forge\u002Fdata` |\n| Port 4444 not accessible on WSL2 | Configure WSL integration in Docker Desktop |\n| Gateway exits immediately | Copy `.env.example` to `.env` and configure required vars |\n| `ModuleNotFoundError` | Run `make install-dev` |\n\nFor detailed troubleshooting guides, see **[Troubleshooting Documentation](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Ftroubleshooting\u002F)**.\n\n---\n\n## Contributing\n\n1. Fork the repo, create a feature branch.\n2. Run `make lint` and fix any issues.\n3. Keep `make test` green.\n4. Open a PR with signed commits (`git commit -s`).\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)** for full guidelines and **[Issue Guide #2502](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2502)** for how to file bugs, request features, and find issues to work on.\n\n---\n\n## Changelog\n\nA complete changelog can be found here: [CHANGELOG.md](.\u002FCHANGELOG.md)\n\n## License\n\nLicensed under the **Apache License 2.0** - see [LICENSE](.\u002FLICENSE)\n\n\n## Core Authors and Maintainers\n\n- [Mihai Criveti](https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fcrivetimihai) - Distinguished Engineer, Agentic AI\n\nSpecial thanks to our contributors for helping us improve ContextForge:\n\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fgraphs\u002Fcontributors\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_fedfb6102ea2.png\" alt=\"Contributors to the mcp-context-forge repository\" \u002F>\n\u003C\u002Fa>\n\n## Star History and Project Activity\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_7e0a38db4724.png)](https:\u002F\u002Fwww.star-history.com\u002F#ibm\u002Fmcp-context-forge&Date)\n\n\u003C!-- === Usage Stats === -->\n[![PyPi Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_readme_cc97620d43e2.png)](https:\u002F\u002Fpepy.tech\u002Fproject\u002Fmcp-contextforge-gateway) \n[![Stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fibm\u002Fmcp-context-forge?style=social)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fstargazers) \n[![Forks](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002Fibm\u002Fmcp-context-forge?style=social)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fnetwork\u002Fmembers) \n[![Contributors](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcontributors\u002Fibm\u002Fmcp-context-forge)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fgraphs\u002Fcontributors) \n[![Last Commit](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002Fibm\u002Fmcp-context-forge)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fcommits) \n[![Open Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002Fibm\u002Fmcp-context-forge)](https:\u002F\u002Fgithub.com\u002Fibm\u002Fmcp-context-forge\u002Fissues) ","# ContextForge 快速上手指南\n\nContextForge 是一个开源的注册中心和代理网关，旨在将 MCP、A2A 以及 REST\u002FgRPC API 联邦化，为 AI 客户端提供统一的接入点。它支持集中式治理、服务发现、可观测性，并优化了 Agent 与工具的调用流程。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows (PowerShell)\n*   **Python 版本**：≥ 3.11\n*   **可选工具**：\n    *   `uv`：推荐的极速 Python 包管理器和运行器（比 pip 更快）。\n    *   `curl` 和 `jq`：用于后续的服务健康检查测试。\n\n> **国内加速建议**：\n> 如果使用 `pip` 安装，建议配置国内镜像源以提升下载速度：\n> ```bash\n> export PIP_INDEX_URL=https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n> # 或在命令中临时指定：pip install -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple ...\n> ```\n\n## 安装步骤\n\n您可以选择使用 `uv`（推荐，单命令启动）或传统的 `pip` + 虚拟环境方式。\n\n### 方式一：使用 uv 快速启动（推荐）\n\n无需手动创建虚拟环境，`uvx` 会自动处理依赖隔离。\n\n```bash\n# 1. 复制示例配置文件并自定义（可选但推荐）\ncurl -O https:\u002F\u002Fraw.githubusercontent.com\u002FIBM\u002Fmcp-context-forge\u002Fmain\u002F.env.example\ncp .env.example .env\n# 编辑 .env 文件修改密码等敏感信息\n\n# 2. 直接运行网关\n# 注意：首次运行会自动下载 mcp-contextforge-gateway 包\nBASIC_AUTH_PASSWORD=pass \\\nMCPGATEWAY_UI_ENABLED=true \\\nMCPGATEWAY_ADMIN_API_ENABLED=true \\\nPLATFORM_ADMIN_EMAIL=admin@example.com \\\nPLATFORM_ADMIN_PASSWORD=changeme \\\nPLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\" \\\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n```\n\n### 方式二：使用 pip 和虚拟环境\n\n适合需要长期开发或深度定制的场景。\n\n```bash\n# 1. 创建项目目录和虚拟环境\nmkdir mcpgateway && cd mcpgateway\npython3 -m venv .venv\n\n# 激活虚拟环境\n# Linux\u002FmacOS:\nsource .venv\u002Fbin\u002Factivate\n# Windows (PowerShell):\n# .\\.venv\\Scripts\\Activate.ps1\n\n# 2. 升级 pip 并安装 ContextForge\npip install --upgrade pip\npip install mcp-contextforge-gateway\n# 国内用户可使用：pip install -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple mcp-contextforge-gateway\n\n# 3. 配置环境变量\n# 方法 A: 导出变量到当前会话\nexport MCPGATEWAY_UI_ENABLED=true\nexport MCPGATEWAY_ADMIN_API_ENABLED=true\nexport PLATFORM_ADMIN_EMAIL=admin@example.com\nexport PLATFORM_ADMIN_PASSWORD=changeme\nexport PLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\"\nexport JWT_SECRET_KEY=\"my-test-key-but-now-longer-than-32-bytes\"\n\n# 方法 B: 或者直接使用 .env 文件 (需确保代码支持加载)\n# curl -O https:\u002F\u002Fraw.githubusercontent.com\u002FIBM\u002Fmcp-context-forge\u002Fmain\u002F.env.example\n# cp .env.example .env\n\n# 4. 启动服务\nmcpgateway --host 0.0.0.0 --port 4444\n```\n\n## 基本使用\n\n服务启动后，默认监听在 `http:\u002F\u002F0.0.0.0:4444`。以下是验证服务和获取访问令牌的最简流程。\n\n### 1. 生成访问令牌 (Bearer Token)\n\nContextForge 默认使用 JWT 进行认证。使用内置工具生成一个临时令牌：\n\n```bash\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n    --username admin@example.com \\\n    --exp 10080 \\\n    --secret my-test-key-but-now-longer-than-32-bytes)\n```\n\n> **Windows PowerShell 用户**请使用以下命令生成令牌：\n> ```powershell\n> $Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `\n>     --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n> ```\n\n### 2. 测试 API 连通性\n\n使用 `curl` 请求版本接口，确认服务正常运行：\n\n```bash\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http:\u002F\u002F127.0.0.1:4444\u002Fversion | jq\n```\n\n如果返回类似 `{\"version\": \"...\"}` 的 JSON 数据，说明网关已成功启动。\n\n### 3. 访问管理后台\n\n如果在启动时设置了 `MCPGATEWAY_UI_ENABLED=true`，您可以直接在浏览器中访问管理界面：\n\n*   **地址**: `http:\u002F\u002Flocalhost:4444\u002F`\n*   **登录账号**: 您在环境变量中设置的 `PLATFORM_ADMIN_EMAIL` (例如: `admin@example.com`)\n*   **登录密码**: 您设置的 `PLATFORM_ADMIN_PASSWORD` (例如: `changeme`)\n\n在管理后台中，您可以注册新的 MCP 服务器、配置 REST API 映射、查看实时日志以及管理插件。","某金融科技公司正在构建一个智能投顾系统，需要让 AI 代理同时调用内部风控模型（gRPC）、外部行情数据（REST）以及第三方分析工具（MCP），以实时生成投资建议。\n\n### 没有 mcp-context-forge 时\n- **接口碎片化严重**：开发团队需为每种协议（gRPC、REST、MCP）编写独立的适配代码，导致代理逻辑复杂且难以维护。\n- **缺乏统一治理**：无法集中管理鉴权与限流策略，某个高频调用的行情接口容易因过载而拖垮整个服务。\n- **可观测性缺失**：当投资建议出错时，难以追踪请求究竟是在哪个环节、哪个协议转换中失败，排查问题如同“盲人摸象”。\n- **扩展成本高昂**：每接入一个新的数据源或工具，都需要修改核心路由代码并重新部署，响应业务需求速度慢。\n\n### 使用 mcp-context-forge 后\n- **统一接入入口**：mcp-context-forge 将异构的 gRPC、REST 和 MCP 接口联邦为单一端点，AI 代理只需通过标准协议即可透明调用所有工具。\n- **集中式防护网**：在网关层统一配置速率限制与身份验证，自动拦截异常流量，确保核心风控模型的稳定性。\n- **全链路追踪**：内置 OpenTelemetry 支持，可清晰可视化每个请求在不同协议间的流转路径，秒级定位故障根源。\n- **插件化热扩展**：利用其丰富的插件生态，新增数据源仅需配置即可生效，无需改动代理核心代码，大幅缩短上线周期。\n\nmcp-context-forge 通过屏蔽底层协议差异并提供统一的治理与观测能力，让企业能像搭积木一样高效构建稳健的 AI 应用架构。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-context-forge_3ca8dee7.gif","IBM","International Business Machines","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FIBM_251be740.jpg","Open Source @ IBM",null,"ibmdeveloper","https:\u002F\u002Fwww.ibm.com\u002Fopensource\u002F","https:\u002F\u002Fgithub.com\u002FIBM",[81,85,89,93,96,100,104,107,111,114],{"name":82,"color":83,"percentage":84},"Python","#3572A5",80.2,{"name":86,"color":87,"percentage":88},"JavaScript","#f1e05a",8.3,{"name":90,"color":91,"percentage":92},"HTML","#e34c26",3.9,{"name":94,"color":95,"percentage":92},"Rust","#dea584",{"name":97,"color":98,"percentage":99},"Makefile","#427819",1.8,{"name":101,"color":102,"percentage":103},"Go","#00ADD8",0.8,{"name":105,"color":106,"percentage":103},"Shell","#89e051",{"name":108,"color":109,"percentage":110},"Dockerfile","#384d54",0.1,{"name":112,"color":113,"percentage":110},"CSS","#663399",{"name":115,"color":116,"percentage":110},"Jinja","#a52a22",3529,614,"2026-04-06T18:01:17","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":124,"python":125,"dependencies":126},"该工具是一个基于 Python 的 API 网关和注册中心，主要用于联邦 MCP、A2A 和 REST\u002FgRPC 服务，不涉及重型 AI 模型推理，因此无特定 GPU 需求。支持通过 PyPI、Docker 或 Kubernetes 部署。可选依赖 Redis 用于缓存和多集群联邦。推荐使用 uv 进行快速安装和环境管理。","3.11+",[127,128,129],"mcp-contextforge-gateway","uv","redis",[35,14,13,15,52],[132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151],"agents","ai","api-gateway","asyncio","authentication-middleware","devops","docker","fastapi","federation","gateway","generative-ai","jwt","kubernetes","llm-agents","mcp","model-context-protocol","observability","prompt-engineering","python","tools","2026-03-27T02:49:30.150509","2026-04-07T13:28:54.700209",[155,160,165],{"id":156,"question_zh":157,"answer_zh":158,"source_url":159},22245,"在隐身模式（Incognito Mode）下登录网关时遇到 401 未授权错误，默认的管理员账号和密码是什么？","默认的管理员凭据如下：\n用户名：admin@example.com\n密码：changeme\n\n请尝试使用这些凭据登录。如果问题在最新版本中仍然存在，请确保您使用的是最新的代码版本，因为新版本可能已经更新了登录界面或认证逻辑。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F839",{"id":161,"question_zh":162,"answer_zh":163,"source_url":164},22246,"如何在 MCP Gateway 中注册一个新的 A2A (Agent-to-Agent) 代理？","注册 A2A 代理的步骤如下：\n1. 导航到管理界面 (Admin UI) -> A2A Agents。\n2. 点击 \"Register Agent\" 按钮打开注册表单。\n3. 输入代理的 URL 和名称，系统会验证这些字段。\n4. 提供技能清单 (Skill Manifest)，系统会解析并显示技能（如果是通用类型，则由下游代理处理）。\n5. 保存代理，系统将返回 `201 Created` 状态码并进行健康检查，确认代理可达。\n6. 在代理列表中确认新代理（例如 \"Cheese Agent\"）已可见。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2491",{"id":166,"question_zh":167,"answer_zh":168,"source_url":169},22247,"Claude Desktop 连接 MCP 服务器时报错 \"Invalid OAuth error response\" 或 \"invalid_type\"，如何解决？","该问题通常是由于 Claude 或 Cursor 在处理 `--header` 参数中的 \"Bearer\" 令牌后的空格时渲染不正确导致的。\n\n推荐的解决方案是使用环境变量来传递令牌，而不是直接在参数中包含空格。修改 `claude_desktop_config.json` 如下：\n\n```json\n{\n  \"mcpServers\": {\n    \"open-horizon-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"http:\u002F\u002Flocalhost:4444\u002Fservers\u002FYOUR_SERVER_ID\u002Fmcp\",\n        \"--header\",\n        \"Authorization:${AUTH_TOKEN}\"\n      ],\n      \"env\": {\n        \"AUTH_TOKEN\": \"Bearer \u003Creplace-your-token>\"\n      }\n    }\n  }\n}\n```\n\n将 `\u003Creplace-your-token>` 替换为您的实际令牌。这种配置可以避免参数解析错误。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F1357",[171,176,181,186,191,196,201,206,211,216,221,226,231,236,241],{"id":172,"version":173,"summary_zh":174,"released_at":175},135948,"v1.0.0-RC2","# v1.0.0-RC2 - 安全加固、Admin UI 优化、插件框架与质量提升\n\n发布候选版本 2 专注于 **安全加固**、**Admin UI 优化**、**插件框架解耦** 以及 **质量改进**，共修复了 **148 个问题**。\n\n## 主要成果\n\n**1.0.0-RC2 版本** 为生产环境部署进一步强化了 ContextForge 的安全性：\n\n- **安全加固**：SSRF 严格默认设置、OIDC id_token 验证、OAuth 密钥静态存储保护、WebSocket\u002F反向代理访问控制、令牌作用域默认拒绝、会话所有权强制执行、资源可见性范围控制等，共计加固了 40 多项安全措施。\n- **Admin UI**：针对虚拟服务器编辑、团队选择器、分页、搜索\u002F筛选、iframe\u002F代理支持、插件管理及 OAuth 表单等功能，修复了 30 多处问题。\n- **API 与认证**：修复了令牌生命周期相关问题，强化了团队范围权限的强制执行，支持 CSRF 在多 Pod 环境下的应用，提升了指标一致性，并实现了网关可见性传播功能。\n- **插件系统**：插件框架已从核心组件中完全解耦；新增 Cedar RBAC 插件和基于 IP 的限流功能。\n- **测试**：全面引入 Playwright 自动化测试，通过 mcp-cli 实现 MCP 协议端到端测试，Locust 工具覆盖了 100% 的 API 接口，并完成了 12 份手动测试计划。\n- **新特性**：新增 RBAC 角色管理 API、ALLOW_PUBLIC_VISIBILITY 标志位、统一的搜索\u002F筛选功能、mTLS 支持、多架构构建以及对 EntraID 组限制的支持。\n\n> **安全亮点**：SSRF 防护现已默认启用严格模式（阻止本地回环地址、私有网络访问，并在 DNS 解析失败时采取关闭策略）。WebSocket 中继和反向代理传输功能现已被默认禁用，需通过显式开启的功能标志才能使用。OIDC SSO 流程现在会对 `id_token` 签名进行加密验证。此外，插件框架已与网关内部实现完全解耦。\n\n---\n\n## 破坏性变更\n\n### SSRF 防护默认设置调整为严格模式（[#3101](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fpull\u002F3101)）\n\n**需采取的措施**：三项 SSRF 默认设置已由宽松模式更改为严格模式。\n\n| 设置 | 旧默认值 | 新默认值 |\n|------|----------|----------|\n| `SSRF_ALLOW_LOCALHOST` | `true` | **`false`** |\n| `SSRF_ALLOW_PRIVATE_NETWORKS` | `true` | **`false`** |\n| `SSRF_DNS_FAIL_CLOSED` | `false` | **`true`** |\n\n> **迁移建议**：若需允许特定内部网段访问，可设置 `SSRF_ALLOWED_NETWORKS=[\"10.20.0.0\u002F16\",\"192.168.50.0\u002F24\"]`；或恢复原有行为，将 `SSRF_ALLOW_LOCALHOST=true`、`SSRF_ALLOW_PRIVATE_NETWORKS=true`、`SSRF_DNS_FAIL_CLOSED=false`。\n\n### WebSocket 中继与反向代理默认禁用（[#3101](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fpull\u002F3101)）\n\n| 设置 | 默认值 | 对应端点 |\n|------|--------|----------|\n| `MCPGATEWAY_WS_RELAY_ENABLED` | `false` | `\u002Fws` WebSocket JSON-RPC 中继 |\n| `MCPGATEWAY_REVERSE_PROXY_ENABLED` | `false` | `\u002Freverse-proxy\u002F*` 端点 |\n\n> **迁移建议**：如需使用上述端点，请将相应功能标志设置为 `true`。\n\n### 强制执行 OIDC ID Token 验证（[#3101](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fpull\u002F3101)）\n\n* SSO 回调现将使用提供商的 JWKS 端点对 `id_token` 签名进行加密验证。\n* 新增可选","2026-03-09T04:13:11",{"id":177,"version":178,"summary_zh":179,"released_at":180},135949,"v1.0.0-RC1","# v1.0.0-RC1 - 安全加固、企业级控制与质量提升\n\n本次发布带来了**企业级安全加固**、**全面的 RBAC 改进**以及**生产级别的策略执行**，共修复了**189 个问题**。\n\n## 🏆 主要成果\n\n**版本 1.0.0-RC1** 为企业生产环境部署强化了 ContextForge 的安全性：\n\n- **🔐 31 项功能**：企业级安全控制、统一的策略决策点（Cedar\u002FOPA）、工具熔断机制、会话亲和性、零配置 TLS、提示工程支持、统一搜索、自助密码重置、许可证合规性、编码数据外泄检测器、灵活的 UI 模块\n- **🔧 106 个 Bug 修复**：认证流程、RBAC、管理员界面、MCP 协议、团队管理、多租户支持、预提交钩子、分页、令牌处理、迁移兼容性、SSO\u002FOAuth、会话亲和性\n- **🛡️ 4 项安全加固**：验证器和插件中的 ReDoS 防护、WebSocket 令牌验证、加密与密钥测试\n- **⚡ 9 项性能优化**：插件正则表达式预编译、加密线程池卸载、Cedar 异步处理、llm-guard 优化\n- **🧪 14 项测试改进**：代码覆盖率超过 80% 的准入门槛、JMeter 基准测试、Playwright 功能增强、手动测试计划、本地负载测试、边缘场景边界条件、iFrame 模式\n- **🔧 22 项日常维护任务**：SonarQube 清理、依赖库更新、Helm 改进、代码风格检查修复、CI\u002FCD 迁移验证、模板脚手架搭建\n- **📝 3 项文档更新**：密码重置指南、贡献指南修正\n\n> **安全亮点**：本次发布彻底重构了认证默认配置，使其默认即为安全状态。JWT 令牌现在必须包含 JTI 和过期时间声明，API 端点已禁用 Basic Auth，公共注册默认关闭，并强制实施管理员锁定保护。此外，企业级安全控制还新增了凭证保护、SSRF 防御以及细粒度的 RBAC。\n\n---\n\n## ⚠️ 重大变更\n\n### 🔐 简化认证模型与安全默认设置 ([#2555](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fissues\u002F2555))\n\n**需采取行动**：多项认证默认配置已调整为更安全的值。\n\n#### 令牌验证默认设置\n* **REQUIRE_JTI** 现默认为 `true`——JWT 令牌必须包含 JTI 声明以支持令牌撤销\n* **REQUIRE_TOKEN_EXPIRATION** 现默认为 `true`——JWT 令牌必须包含过期时间声明\n* **PUBLIC_REGISTRATION_ENABLED** 现默认为 `false`——自注册功能默认关闭\n\n> **迁移提示**：现有不包含 JTI 或过期时间声明的令牌将被拒绝。请使用 `python -m mcpgateway.utils.create_jwt_token` 生成新令牌，该工具默认会包含这些声明。\n\n#### AdminAuthMiddleware\n* 新增对 `\u002Fadmin\u002F*` 路径的 API 令牌认证支持\n* 新增平台管理员引导配置支持，用于首次部署场景\n* 统一了与主 API 认证一致的认证方式\n* 管理员界面采用基于会话的邮箱\u002F密码登录\n\n#### Basic Auth 配置\n* **API_ALLOW_BASIC_AUTH** 现默认为 `f","2026-02-18T14:25:50",{"id":182,"version":183,"summary_zh":184,"released_at":185},135950,"v1.0.0-BETA-2","本次发布带来了**大幅性能提升**、**企业级可靠性**以及**生产环境加固**，共修复了**227个问题**。\n\n## 🏆 主要成就\n\n**1.0.0-BETA-2 版本** 为生产部署带来了变革性的升级：\n\n- **⚡ 100+ 项性能优化** - 消除 N+1 查询、连接池化（PgBouncer）、缓存机制（L1\u002FL2）、Granian HTTP 服务器、orjson 序列化等\n- **🔧 80+ 个 Bug 修复** - RBAC、分页、OAuth、Admin UI、多租户以及 MCP 协议兼容性等方面的问题\n- **🔐 安全增强** - JWT 生命周期管理、环境隔离、团队成员资格验证\n- **🏗️ 平台扩展** - 支持 ppc64le（IBM POWER）架构、外部 PostgreSQL 集成、Helm 工具改进\n- **📊 可观测性** - Prometheus\u002FGrafana 监控配置、指标聚合优化、详细请求日志记录\n\n> **性能亮点**：在持续负载测试（10,000+ 并发用户）下，通过消除 N+1 查询，延迟降低了 **10 倍以上**；借助 PgBouncer 连接池，连接数减少了 **50% 以上**；而使用 Granian HTTP 服务器后，吞吐量提升了 **3 倍以上**。\n\n---\n\n## ⚠️ 重大变更\n\n### 🐘 PostgreSQL 驱动迁移：psycopg2 → psycopg3\n\n**必须操作**：请更新 `DATABASE_URL` 连接字符串格式。\n\n```bash\n# 旧版 (psycopg2) - 已不再支持\nDATABASE_URL=postgresql:\u002F\u002Fpostgres:password@localhost:5432\u002Fmcp\n\n# 新版 (psycopg3) - 必须采用此格式\nDATABASE_URL=postgresql+psycopg:\u002F\u002Fpostgres:password@localhost:5432\u002Fmcp\n```\n\n**为何进行此更改？**\n- **psycopg3** 提供原生异步支持、更优的性能和更强的连接管理能力。\n- 消除了在 ARM64 和 Alpine Linux 上使用 `psycopg2-binary` 时可能出现的依赖问题。\n- 为与 PgBouncer 事务连接池的兼容性所必需。\n\n**迁移步骤：**\n1. 将 `DATABASE_URL` 更新为以 `postgresql+psycopg:\u002F\u002F` 开头的格式。\n2. 重启网关服务——无需数据迁移。\n3. 对于使用 Docker Compose 的用户：请更新 `.env` 文件或 `docker-compose.yml`。\n\n### 🔌 联邦自动发现功能已弃用\n\n- **移除 `DiscoveryService`** - mDNS\u002FZeroconf 自动发现功能已不再支持。\n- **移除 `ForwardingService`** - 其功能现已整合至 `ToolService` 中。\n- **废弃以下环境变量：** `FEDERATION_ENABLED`、`FEDERATION_DISCOVERY`、`FEDERATION_PEERS`、`FEDERATION_SYNC_INTERVAL`。\n- **保留：** 用于网关请求超时设置的 `FEDERATION_TIMEOUT`。\n- **不受影响：** 通过 `\u002Fgateways` REST API 进行的网关对等节点管理功能仍完全可用。\n\n---\n\n## ✨ 核心亮点\n\n### 🛑 网关协调的工具取消机制\n\n**实时取消长时间运行的工具执行任务**\n\n全新的取消系统由网关统一管控正在运行的工具操作，并实现多工作器间的协同配合。\n\n#### 功能特性\n- **REST API 端点** - `POST \u002Fcancellation\u002Fcancel` 和 `GET \u002Fcancellation\u002Fstatus\u002F{request_id}`\n- **真正的任务中断** - 实际执行 asyncio 任务的取消，而非…","2026-01-24T15:59:13",{"id":187,"version":188,"summary_zh":189,"released_at":190},135951,"v1.0.0-BETA-1","本次发布标志着 **迈向 1.0.0 GA 的首个 Beta 阶段里程碑**，带来了 **多架构容器支持**、**gRPC 至 MCP 协议转换**、**气隙部署能力**，以及在修复了 **25 多个问题** 后实现的 **显著性能提升**。\n\n## 🎉 新闻公告\n\n### 🖥️ ContextForge 桌面应用\n\n我们很高兴地宣布推出 **ContextForge 桌面应用**——一款用于管理 MCP 服务器和网关的原生桌面客户端：\n\n- **仓库地址：** [contextforge-org\u002Fcontextforge-desktop](https:\u002F\u002Fgithub.com\u002Fcontextforge-org\u002Fcontextforge-desktop)\n- 跨平台支持（Windows、macOS、Linux）\n- 可视化的 MCP 服务器管理和监控\n- 集成式网关配置功能\n\n### ⌨️ ContextForge 命令行工具\n\n面向 ContextForge 操作的全新命令行界面：\n\n- **仓库地址：** [contextforge-org\u002Fcontextforge-cli](https:\u002F\u002Fgithub.com\u002Fcontextforge-org\u002Fcontextforge-cli)\n- 支持脚本化的 MCP 服务器和网关管理\n- 提供 CI\u002FCD 集成支持\n- 包含配置导出与导入实用工具\n\n### 🏢 新成立的 ContextForge 组织\n\n我们已创建 [contextforge-org](https:\u002F\u002Fgithub.com\u002Fcontextforge-org) GitHub 组织，用于托管不断壮大的 ContextForge 生态系统。在接下来的版本中，多个组件将迁移到该组织：\n\n- 插件\n- MCP 服务器\n- 代理运行时\n- 桌面及命令行工具\n\n> **注意：** 主要的网关仓库仍位于 [IBM\u002Fmcp-context-forge](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge)。\n\n---\n\n## 🏆 重大成果\n\n**1.0.0-BETA-1 版本** 是迈向生产就绪的重要里程碑：\n\n✅ **🏗️ 多架构容器支持** - 现已支持 ARM64 和 s390x 架构，适用于 Apple Silicon、AWS Graviton 以及 IBM Z 等环境的部署  \n✅ **🔌 gRPC 至 MCP 协议转换** - 实验性 gRPC 服务接口，基于 Protocol Buffers 实现 MCP 协议操作  \n✅ **🌐 气隙部署** - 提供 CDN 资源打包功能，支持完全离线或断网环境  \n✅ **⚡ 性能提升超 10 倍** - 并发健康检查与 N+1 查询优化大幅降低网关操作延迟  \n✅ **🔐 密码过期策略** - 可配置密码有效期，并强制用户登录时更改密码  \n✅ **🔑 一次性认证** - 支持 WXO 集成，使用一次性的认证令牌  \n✅ **🛡️ 输入验证与转义** - 在网关层面增强安全性，防止路径遍历和注入攻击  \n✅ **🧪 性能测试框架** - 构建了全面的基准测试基础设施，可检测 N+1 查询问题  \n\n---\n\n## ✨ 核心亮点\n\n### 🏗️ 多架构容器支持\n\n**在任何地方都能以原生性能运行**\n\nMCP 网关现已能够构建适用于多种 CPU 架构的容器镜像，从而支持在多样化基础设施上的部署：\n\n#### 支持的架构\n- **linux\u002Famd64** - 标准 x86_64 服务器及云实例  \n- **linux\u002Farm64** - Apple Silicon（M1\u002FM2\u002FM3）、AWS Graviton、Raspberry Pi 4 及更高版本  \n- **linux\u002Fs390x** - 适用于企业级的 IBM Z\u002FLinuxONE 大型机","2025-12-16T20:14:34",{"id":192,"version":193,"summary_zh":194,"released_at":195},135952,"v0.9.0","本次发布带来了**详细的内部可观测性**、**重大性能提升、压缩与分页功能**、**REST API 直通**、**Ed25519 证书签名**以及**关键的多租户修复**，共解决了**60 多个问题**，合并了**50 多个 Pull Request**。\n\n\n## 🏆 主要成就\n\n**版本 0.9.0** 是在生产就绪性和运营卓越方面的一个重要里程碑：\n\n✅ **📊 内置可观测性平台** - 自包含的性能监控，配备交互式仪表盘、甘特图、火焰图和全面的链路分析（无需外部平台！）\n✅ **⚡ 带宽降低 30%-70%** - 多种算法响应压缩（Brotli、Zstd、GZip），且无需客户端改动\n✅ **🚀 JSON 处理速度提升 5-6 倍** - 使用 orjson 序列化实现高吞吐量 API，同时负载减少 7%\n✅ **🦀 插件性能提升 5-100 倍** - Rust 加速的 PII 过滤器，并具备自动 Python 回退机制\n✅ **📄 全面分页支持** - 基于 HTMX 的 UI 分页功能，经测试可处理多达 1 万条记录，并结合数据库优化\n✅ **🔌 REST API 直通** - 完整的 REST 工具配置，支持查询\u002F头部映射及插件链\n✅ **🔐 Ed25519 证书签名** - 生产就绪的证书认证，支持零停机密钥轮换\n✅ **🛡️ 多租户安全修复** - 关键的 RBAC 漏洞修补及所有权强制执行\n✅ **💬 LLM 聊天界面** - 内置 MCP 客户端，采用 Redis 实现会话一致性，适用于分布式环境\n\n---\n\n## ✨ 亮点\n\n### 📊 内部可观测性系统（新！）\n\n**自包含的性能监控与链路分析，无需外部依赖**\n\n0.9.0 版本最大的特性是全新的内置可观测性系统，可在您的数据库（SQLite\u002FPostgreSQL\u002FMariaDB）中完整存储生产级的监控、追踪和分析数据，并通过管理界面提供**交互式可视化**。\n\n#### 核心能力\n\n**性能分析**\n- **延迟百分位数**：p50、p90、p95、p99 等指标，用于深入性能分析\n- **持续时间跟踪**：所有操作的毫秒级精确计时\n- **吞吐量指标**：随时间变化的请求数量与速率\n- **对比分析**：多资源并行比较\n\n**错误追踪**\n- **错误率监控**：失败操作占比，以颜色编码健康状态\n  - 🟢 绿色：\u003C5% 错误（健康）\n  - 🟡 黄色：5%-20% 错误（性能下降）\n  - 🔴 红色：>20% 错误（不健康）\n- **易错资源分析**：识别故障率最高的资源\n- **状态码追踪**：HTTP 响应码及错误信息\n- **根因分析**：附带完整上下文的详细调用链\n\n**交互式仪表盘**\n- **工具仪表盘**（`\u002Fadmin\u002Fobservability\u002Ftools`）：MCP 工具调用指标\n- **提示仪表盘**（`\u002Fadmin\u002Fobservability\u002Fprompts`）：提示渲染性能\n- **资源仪表盘**（`\u002Fadmin\u002Fobservability\u002Fresources`）：资源获取操","2025-11-09T22:05:14",{"id":197,"version":198,"summary_zh":199,"released_at":200},135953,"v0.8.0","## v0.8.0 - 2025-10-07 - 高级 OAuth、插件生态与 MCP 注册中心\n\n本次发布聚焦于 **高级 OAuth 集成、插件生态与 MCP 注册中心**，共修复了 **50 多个问题**，合并了 **47 个 Pull Request**，在认证、插件框架和开发者体验等方面带来了显著提升。基于 v0.7.0 版本的企业级多租户基础，本次发布通过先进的 OAuth 流程、完善的插件生态以及增强的 MCP 服务器发现能力，进一步扩展了 MCP Gateway 的功能。\n\n---\n\n## 🏆 插件生态与高级认证成果\n\n**0.8.0 版本** 提供了一个 **生产就绪的插件框架**，内置了 **15 余款插件**，配备了完整的 **插件管理 UI 和 API**，并支持 **高级 OAuth 2.0**，包括密码授权模式、动态客户端注册（DCR）以及 PKCE。此次发布将 MCP Gateway 打造成一个高度可扩展的平台，同时保持企业级的安全性和多租户能力。\n\n### 主要成就\n\n✅ **15+ 款生产就绪插件** - 涵盖安全、内容审核、缓存、格式化和监控等领域的完整插件库  \n✅ **插件管理 UI 和 API** - 通过管理控制台实现插件全生命周期管理  \n✅ **高级 OAuth 集成** - 支持密码授权模式、带 PKCE 的 DCR、令牌刷新及多租户场景  \n✅ **MCP 服务器注册中心** - 本地目录，优化了发现、搜索和注册流程  \n✅ **多租户能力增强** - 团队级别的 API 令牌作用域划分，以及所有管理表格中的团队可见性  \n✅ **OPA 策略增强** - 可自定义策略路径、多架构支持，并改进了输入映射\n\n---\n\n## ✨ 亮点\n\n### 🔐 高级 OAuth 与认证\n- **OAuth 密码授权模式** - 完整实现，适用于程序化认证场景  \n- **OAuth 动态客户端注册（DCR）** - 全面支持 PKCE，提升安全性  \n- **令牌刷新机制** - 支持多租户感知的令牌处理，并实现自动刷新  \n- **安全 Cookie 警告** - 为 HTTP 开发环境提供清晰指引  \n- **OAuth2 网关编辑功能** - 在不更改 URL 的情况下编辑网关时，保留工具\u002F资源\u002F提示信息  \n\n### 🔌 插件生态扩展\n- **15+ 款内置插件** - 包括安全、内容审核、缓存等领域的生产就绪插件  \n- **插件管理 UI** - 专用管理界面，用于插件配置和监控  \n- **插件框架规范** - 提供全面的插件开发文档  \n- **外部插件支持** - 支持加载和管理第三方插件，并进行配置管理  \n\n### 📦 MCP 服务器注册中心与目录\n- **本地 MCP 服务器目录** - 中心化的注册中心，用于 MCP 服务器的发现与管理  \n- **搜索功能增强** - 优化目录浏览，新增高级搜索能力  \n- **目录用户体验改进** - 简化服务器注册和发现的用户流程  \n- **示例","2025-10-08T00:34:31",{"id":202,"version":203,"summary_zh":204,"released_at":205},135954,"v0.7.0","# MCP 网关 v0.7.0 - 2025-09-16 - 企业级多租户、RBAC、团队、SSO\n\n本次发布修复了 **50 多个问题**，并实现了 MCP 网关从单租户系统向 **多租户平台** 的 **根本性架构转型**，支持基于团队的资源范围控制、企业级 SSO 集成以及高级数据库支持。\n\n## 🏆 企业级多租户与安全成就\n\n本次发布实现了 **[EPIC #860]：完整的基于团队的资源范围控制的企业级多租户系统**，将 MCP 网关转变为真正的企业级平台（[架构指南](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Fmultitenancy\u002F)），具备以下特性：\n\n* **🔐 完整的身份认证体系** – 基于电子邮件的认证，采用 Argon2id 密码哈希算法替代基础认证\n* **👥 多租户团队管理** – 支持个人团队、邀请机制及基于角色的访问控制，实现团队全生命周期管理\n* **🔒 三层资源可见性** – 所有实体类型均支持私有\u002F团队\u002F公开的资源范围控制\n* **🌐 多提供商 SSO 框架** – 集成 GitHub、Google 和 IBM Security Verify，并支持域信任\n* **🗄️ 增强的数据库支持** – 在 PostgreSQL 和 SQLite 的基础上，全面支持 MariaDB 和 MySQL 生产环境\n* **🔑 高级 JWT 安全性** – 支持非对称算法（RSA、ECDSA），并提供受众验证和动态客户端注册功能\n* **⚡ 性能优化** – 针对多租户工作负载配置数据库连接池\n\n## ✨ 亮点\n\n* 🔐 **电子邮件认证系统** – 实现完整的用户认证，采用 Argon2id 密码哈希算法，并支持可配置的密码策略 (#544, #426)\n* 👥 **完整的 RBAC 与团队系统** – 提供平台管理员、团队所有者、团队成员等角色，全面支持多租户功能 (#283, #860)\n* 🌐 **多提供商 SSO 集成** – 支持 GitHub、Google 和 IBM Security Verify，并集成企业域信任机制 (#220, #278, #859)\n* 🔑 **非对称 JWT 支持** – 支持 RSA 和 ECDSA 算法，具备企业级安全特性及受众验证功能\n* 🗄️ **MariaDB 和 MySQL 支持** – 全面支持兼容 MySQL 的数据库，并保留所有功能 (#925)\n* 🔒 **按虚拟服务器的 API 密钥** – 为每个虚拟服务器生成具有团队上下文的受限访问令牌 (#282)\n* 📊 **优化的数据库模式** – 针对多租户场景进行优化，添加了适当的索引并考虑性能因素\n\n### 🚨 重要迁移通知\n\n* **重大数据库迁移** – 本次发布需要将数据库模式从单租户迁移到多租户模式\n* **认证方式变更** – 从基于用户名的认证方式迁移至基于电子邮件的认证方式\n* **配置更新** – 新增用于多租户功能的环境变量\n* **完整迁移指南** – 请参阅 `MIGRATION-0.7.0.md` 获取详细的升级说明\n\n## 🆕 新增功能\n\n### 🔐 身份认证与授权系统\n\n* **基于电子邮件的用户认证** (#544) – 完全替换原有的基础认证，采用电子邮件\u002F密","2025-09-16T17:29:25",{"id":207,"version":208,"summary_zh":209,"released_at":210},135955,"v0.6.0","# MCP 网关 v0.6.0 - 2025-08-22 - 安全、规模与智能自动化\n\n本次发布包含 **118 次提交** 和 **50 多个已解决的问题**，在可扩展性、智能化和企业级运维能力方面实现了变革性的提升。基于 v0.5.0 的安全基础，`v0.6.0` 引入了革命性的插件架构、AI 代理集成以及全面的可观测性。\n\n## 🏆 企业级规模与自动化成果\n\n本次发布将 MCP 网关打造为真正的企业级平台，具备以下特性：\n\n* **🔌 插件框架** – 全面的可扩展架构，支持前置\u002F后置钩子及外部插件\n* **🤖 A2A 代理集成** – 原生支持 OpenAI、Anthropic 以及自定义代理作为工具\n* **📊 OpenTelemetry 可观测性** – 与供应商无关的可观测性，集成 Phoenix 并支持分布式追踪\n* **🔄 批量导入系统** – 企业级批量操作功能，支持一次导入 200 个工具，并提供速率限制\n* **💾 实时日志查看器** – 内置日志监控功能，支持高级过滤和导出\n* **🏷️ 全面标签管理** – 基于标签的组织与筛选，覆盖所有实体\n* **⚡ 性能优化** – 增强缓存机制、连接优化以及变异测试\n\n## ✨ 亮点\n\n* 🔌 **插件框架** – 完整的可扩展架构，采用清单式配置并支持外部插件 (#319, #313, #773)\n* 🤖 **A2A 代理集成** – 将 AI 代理作为原生工具，提供全面的指标监控和管理界面支持 (#298, #792)\n* 📊 **OpenTelemetry 可观测性** – 全面的与供应商无关的度量采集，集成 Phoenix (#735, #727)\n* 🔄 **批量导入系统** – 企业级批量工具导入功能，配备速率限制和验证机制 (#737, #798)\n* 💾 **管理员日志查看器** – 基于 SSE 流式传输的实时日志监控，支持高级过滤 (#138, #364)\n* 🏷️ **标签系统** – 在所有实体上实现全面的标签支持与筛选 (#586)\n* 🚀 **MCP 协议增强** – 支持提示工程，并增强了工具注解功能 (#708, #774)\n\n### 🚨 重要更新\n\n* **插件架构** – 新增 `plugins\u002Fconfig.yaml` 配置系统，支持启用\u002F禁用标志\n* **A2A 配置** – 提供全面的 A2A 功能开关，用于控制代理行为\n* **增强的可观测性** – 完整集成 OpenTelemetry，支持分布式追踪\n* **性能改进** – 进行变异测试、异步性能测试，并优化缓存机制\n* **虚拟服务器修复** – 修复了 v0.5.0 中虚拟服务器未能按预期工作的关键问题\n\n## 🆕 新增功能\n\n### 🔌 插件框架与可扩展性\n\n* **全面的插件系统** (#319, #313) – 完整的插件框架，采用清单式配置并提供生命周期管理\n* **请求前置\u002F后置钩子** – 插件钩子可用于拦截和修改所有操作中的请求与响应\n* **工具调用钩子** (#682) – 专门的 `tool_pre_invoke` 和 `tool_post_invoke` 插","2025-08-22T16:58:30",{"id":212,"version":213,"summary_zh":214,"released_at":215},135956,"v0.5.0","这款以企业为中心的版本修复了**42个问题**，并在身份验证、配置管理、错误处理和开发者体验方面实现了重大改进。基于 v0.4.0 的安全基础，`v0.5.0` 引入了增强的 JWT 安全性、全面的 UI\u002FUX 优化，以及对所有端点输入验证的强化。\n\n## 🏆 企业级运维成果\n\n此版本通过以下特性提升了生产就绪度：\n\n* **增强的 JWT 安全性** – 在配置启用时强制执行令牌过期\n* **敏感数据脱敏** – 身份验证凭据在 API 响应中得到妥善隐藏\n* **改进的错误处理** – 提供用户友好的消息及可操作的指导\n* **更高的可观测性** – 改进的状态报告与服务可见性\n* **提升开发者效率** – 针对单个文件的代码检查及 Makefile 的全面优化\n* **更强的输入验证** – 全面的 XSS 防护与所有端点的输入校验\n\n> **重要提示**：Admin UI 仍仅适用于开发环境，并采用了更严格的安全默认设置。请勿将其暴露于生产环境。请基于适当的安全控制构建您自己的生产级 UI。详情请参阅 [Securing MCP Gateway](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fsecuring\u002F) 文档。\n> **Beta 软件声明**：MCP Gateway 目前处于早期 Beta 阶段。小版本之间可能存在破坏性变更。请仅与受信任的上游 MCP 服务器配合使用。本项目为**开源项目**，由社区驱动支持，IBM 不提供官方支持。更多信息请参阅 [SECURITY.md](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002FSECURITY.md) 及我们的 [Roadmap](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F)。\n\n## ✨ 亮点\n\n* 🔐 **JWT 令牌安全性** – 当 `REQUIRE_TOKEN_EXPIRATION=true` 时强制设置过期时间 (#425)\n* 🎭 **身份验证值脱敏** – 所有 API 响应中均隐藏敏感凭据 (#601, #602)\n* 🧪 **测试工具增强** – 默认值支持、数组与布尔值处理、多行文本支持 (#620-#644)\n* 🛠️ **开发者体验** – 使用 `make lint filename` 实现针对特定文件的代码检查 (#410, #660)\n* 📊 **更好的可见性** – 工具\u002F资源概览中新增 MCP 服务器名称列 (#506, #624)\n* 🔍 **安全扫描集成** – 集成 Snyk、DevSkim 和 nodejsscan (#590, #638, #639)\n* ✅ **UI 改进** – 复选框选择优化、错误信息改善、表单修复 (#392, #619)\n* 📝 **SPDX 合规性** – 自动化文件头验证 (#315, #317, #656)\n\n### 🚨 重要更新\n\n* **UI 默认启用** – `.env.example` 现已将 `MCPGATEWAY_UI_ENABLED=true`，便于快速上手\n* **API 文档认证** – 新增 `DOCS_BASIC_AUTH_ENABLED` 标志，用于保护文档端点\n* **增强的验证机制** – 对网关 URL、工具名称及输入参数实施更严格的规则\n* **脚本优化** – 整合 `run-gunicorn.sh` 并改进错误处理 (#397, #430)\n\n## 🆕 新增功能\n\n### 安全与身份验证\n\n* **JWT 令牌过期** (#425) – 强制设置过期时间 with","2025-08-05T23:36:47",{"id":217,"version":218,"summary_zh":219,"released_at":220},135957,"v0.4.0","# 🛡️ MCP 网关 v0.4.0 – 2025-07-22\n\n此里程碑版本在所有代码检查工具上实现了**100% 合规性**，单元测试覆盖率达到82%，doctest 覆盖率达到60%，并新增了 UI 测试自动化功能。同时，该版本还引入了韧性增强特性、全面的测试基础设施以及关键问题修复。共解决了超过52个问题，`v0.4.0` 体现了我们对企业级安全性和代码质量的承诺。\n\n## 🏆 安全与质量成就\n\n本次发布为代码质量和安全性设定了新标准：\n\n* **100% 代码检查合规性** – 在 Bandit、HTMLHint、Stylelint、ESLint、Retire.js 和 nodejsscan 中均无任何问题\n* **100% 文档字符串覆盖率** – 每个函数和类都已完整文档化\n* **Pylint 得分 10\u002F10** – 代码质量评分保持不变\n* **60% doctest 覆盖率** – 通过可执行示例增强了文档说明\n* **82% pytest 覆盖率** – 强化了 pytest 测试套件，新增端到端测试和输入验证\n* **新 test-ui** - 基于 Playwright 的 UI 测试自动化（例如 `make dev & bg; make test-ui-headless`）\n* **智能重试机制** – 具有指数退避策略的韧性连接\n\n> **重要提示：** 管理界面仍仅用于开发环境。请勿在生产环境中暴露该界面。请基于适当的安全控制构建您自己的生产界面。更多信息请参阅 [Securing MCP Gateway](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Fmanage\u002Fsecuring\u002F) 文档。\n> **Beta 软件声明：** MCP 网关目前处于早期 Beta 阶段。预计在小版本之间可能会出现破坏性变更，且部分功能尚未完善。请仅与受信任的上游 MCP 服务器配合使用。本项目为**开源项目**，由社区驱动支持，IBM 不提供官方支持。更多信息及即将推出的功能，请参阅 [SECURITY.md](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fblob\u002Fmain\u002FSECURITY.md) 和我们的 [Roadmap](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F)。\n\n## ✨ 亮点\n\n* 🔒 **零安全漏洞** – 所有安全扫描工具均未发现任何问题 (#421, #415, #552)\n* 🔄 **智能重试机制** – HTTPX 客户端采用指数退避策略，实现韧性连接 (#456)\n* 🧪 **安全测试套件** – 全面的输入验证测试框架 (#552)\n* 🔧 **测试连接工具** – 提供详细诊断信息，帮助调试 MCP 服务器连接 (#181)\n* 💾 **过滤器状态持久化** – UI 过滤器和偏好设置现在可在会话间保持 (#177)\n* 📚 **60% doctest 覆盖率** – 可执行的文档示例 (#249)\n* 🐳 **Docker HEALTHCHECK** – 生产就绪的容器健康监测 (#362)\n* 📊 **E2E 接受测试** – 完整的端到端验证文档 (#399)\n\n### 🚨 重要安全更新\n\n* **持续的安全默认配置** – 管理界面和 API 默认禁用\n* **增强的错误处理** – 将 assert 语句替换为适当的异常处理 (#412)\n* **修复关键漏洞** – 解决了 STREAMABLEHTTP 传输问题 (#213) 和认证失败问题 (#232)\n* **改进输入验证** – 将验证范围扩展至 RPC 端点 (#361)\n\n## 🆕 新增功能\n\n### R","2025-07-22T22:25:43",{"id":222,"version":223,"summary_zh":224,"released_at":225},135958,"v0.3.1","# 🔐 MCP Gateway v0.3.1 – 2025-01-11\r\n\r\nThis security-focused release delivers comprehensive input validation, output escaping, and data sanitization to protect against XSS and injection attacks when handling data from untrusted MCP servers. It also includes UI improvements and code quality enhancements.\r\n\r\n## 🔒 Security First: Defense in Depth\r\n\r\nThis release prioritizes defense in depth with multiple layers of security validation:\r\n\r\n* **Input Validation Framework** – Comprehensive validation for all API endpoints\r\n* **Output Escaping** – HTML-escaped display of user-controlled content in UI\r\n* **Data Sanitization** – Protection against XSS injection from untrusted MCP servers\r\n* **Secure Defaults** – Admin UI and API disabled by default (development-only features)\r\n* **Automated Security Pipeline** – 24+ security tools including CodeQL, Bandit, Trivy, and OSV-Scanner\r\n\r\n> **Important:** The Admin UI is for **development only** and must **never be exposed in production**. It's designed for localhost-only access with trusted MCP servers. For production, disable it completely and use only the REST API with proper authentication.\r\n> **Beta Software Notice**: MCP Gateway is in early beta. Expect breaking changes between minor versions. This is an **OPEN SOURCE PROJECT** with community-driven support and no official support from IBM.\r\n\r\n## ✨ Highlights\r\n\r\n* 🛡️ **Comprehensive Security Hardening** – Input validation for all `\u002Fadmin` and main API endpoints with configurable rules (#339, #340)\r\n* 🔒 **XSS Protection** – Enhanced output handling ensures all user-controlled content is properly HTML-escaped (#336)\r\n* ✅ **Zero Lint Status** – Resolved all 312 code quality issues across the web stack (#338)\r\n* 🔧 **Test Connectivity Tool** – New debugging feature to validate gateway connections (#181)\r\n* 💾 **Persistent UI State** – Filters and view preferences now persist across page refreshes (#177)\r\n* 🎨 **Revamped UI Components** – Metrics and version tabs rewritten for consistency\r\n* 🧪 **UI-Disabled Mode Support** – Fixed unit tests to handle configurations with UI disabled (#378)\r\n* 🏷️ **Semantic Versioning** – Version endpoint now includes proper semantic version, not just git revision (#369)\r\n\r\n### 🚨 Important Limitations\r\n\r\n* **Not Multi-Tenant Ready** – Deploy as single-tenant component; implement user isolation, RBAC, and resource management in your application layer - many of the features to support true multi-tenancy and additional security policies and tools are coming slated for [release 0.7.0 - 0.8.0](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002Farchitecture\u002Froadmap\u002F#release-070-multitenancy-and-rbac)\r\n* **Admin UI is Development-Only** – Never expose in production; build your own production UI with appropriate security controls\r\n* **Beta Software** – Validate all MCP servers before connecting; expect breaking changes between releases\r\n\r\n## 🆕 Added\r\n\r\n### Security Enhancements\r\n\r\n* **Comprehensive Input Validation Framework** (#339, #340):\r\n  * All `\u002Fadmin` endpoints validated – tools, resources, prompts, gateways, and servers\r\n  * All non-admin API endpoints validated for consistent data integrity\r\n  * Configurable validation rules with sensible defaults:\r\n    - Character restrictions: names `^[a-zA-Z0-9_\\-\\s]+$`, tool names `^[a-zA-Z][a-zA-Z0-9_]*$`\r\n    - URL scheme validation: `http:\u002F\u002F`, `https:\u002F\u002F`, `ws:\u002F\u002F`, `wss:\u002F\u002F`\r\n    - JSON nesting depth limits (default: 10 levels)\r\n    - Field-specific length limits (names: 255, descriptions: 4KB, content: 1MB)\r\n    - MIME type validation for resources\r\n  * Clear error messages guide users to correct input formats\r\n\r\n* **Enhanced Output Handling** (#336):\r\n  * All user-controlled content properly HTML-escaped in Admin UI\r\n  * Protected fields: prompt templates, tool names\u002Fannotations, resource content, gateway configs\r\n  * Ensures data displays as intended without unexpected behavior\r\n\r\n### Features\r\n\r\n* **Test MCP Server Connectivity Tool** (#181) – Debug and validate gateway connections from Admin UI\r\n* **Persistent Admin UI Filter State** (#177) – View preferences persist across refreshes\r\n* **Revamped UI Components** – Metrics and version tabs rewritten for consistency\r\n\r\n### Fixes\r\n\r\n* **Unit Test Compatibility** (#378) – Tests now properly handle UI-disabled mode configurations\r\n* **Version Endpoint Enhancement** (#369) – Now includes semantic version (e.g., \"0.3.1\") not just git revision\r\n\r\n## 🔄 Changed\r\n\r\n* **Code Quality Achievement** (#338):\r\n  * Resolved all 312 code quality issues\r\n  * Updated 14 JavaScript patterns\r\n  * Corrected 2 HTML structure improvements\r\n  * Standardized naming conventions\r\n  * Removed unused code\r\n\r\n* **Security Defaults**:\r\n  * Admin UI disabled by default: `MCPGATEWAY_UI_ENABLED=false`\r\n  * Admin API disabled by default: `MCPGATEWAY_ADMIN_API_ENABLED=false`\r\n  * Update your `.env` file to explicitly enable these features\r\n\r\n* **Validation Configuration** – New environment variables:\r\n  ```bash\r\n  VALIDATION_MAX_NAME_LENGTH=255\r\n  ","2025-07-11T03:13:46",{"id":227,"version":228,"summary_zh":229,"released_at":230},135959,"v0.3.0","# 🚀 MCP Gateway v0.3.0 – 2025-07-08\r\n\r\nThis **milestone release** delivers powerful **multi-server tool federations** with rich annotations, enhanced UI management capabilities, and rock-solid stability improvements that make MCP Gateway ready for production workloads.\r\n\r\n**Note:** This release introduces Alembic migrations to make future database schema changes seamless. These happen automatically, but in some cases, when upgrading from 0.1.0 - migration may not be possible and you will need to re-create your database. Ex: `rm mcp.db`.\r\n\r\n## ✨ Highlights\r\n\r\n* 🔗 **Multi-Server Tool Federation** – seamlessly aggregate tools, resources, and prompts across multiple MCP servers with intelligent namespace handling and UUID-based identity management.\r\n* 🏷️ **Rich Annotations & Metadata** – enhanced tool and resource annotations with dynamic UI pickers for better discoverability and management.\r\n* 🔄 **Auto-Recovery & Resilience** – automatic MCP server reactivation when services come back online, plus configurable connection retries with exponential backoff.\r\n* 🎯 **Dynamic UI Management** – intuitive pickers for tool, resource, and prompt associations with real-time server status indicators.\r\n* 📤 **Enhanced Connection Export** – one-click connection string generation for popular AI frameworks and clients.\r\n* 🛠️ **Developer Experience** – comprehensive workstation setup guides, improved error handling, and cleaner database migrations.\r\n* 🐹 **Go MCP Server Reference** – fast-time-server implementation showcasing best practices for high-performance MCP servers.\r\n\r\n## 🆕 Added\r\n\r\n* **Namespace Composite Keys & UUIDs** for robust tool identity across federated servers.\r\n* **Dynamic UI Picker** for tool, resource, and prompt associations with live server filtering.\r\n* **Auto-activation system** that automatically re-enables MCP servers when they recover.\r\n* **Configurable connection retries** for databases and Redis with intelligent backoff strategies.\r\n* **Enhanced connection string export** API and UI for seamless client integration.\r\n* **Go-based fast-time-server** as a high-performance MCP server reference implementation.\r\n* **Developer Workstation Setup Guide** covering Mac (Intel\u002FARM), Linux, and Windows environments.\r\n* **Improved file lock handling** with proper `\u002Ftmp` directory usage for better multi-instance support.\r\n\r\n## 🔄 Changed\r\n\r\n* **Database schema migration** with separate `enabled` and `reachable` fields replacing the legacy `is_active` field.\r\n* **Enhanced path parameter handling** for REST API virtualization with better substitution logic.\r\n* **Streamlined packaging** with proper Alembic configuration inclusion in PyPI wheels.\r\n* **Modernized Pydantic patterns** eliminating deprecation warnings and improving type safety.\r\n* **Improved UI responsiveness** with better parameter input modal handling and validation.\r\n\r\n## 🐛 Fixed\r\n\r\n* **Database migration packaging** – Alembic configurations now properly included in pip installations.\r\n* **Field migration handling** – smooth transition from `is_active` to `enabled`\u002F`reachable` fields.\r\n* **File lock path creation** – proper `\u002Ftmp` directory usage instead of current working directory.\r\n* **GitHub Remote Server** addition flow now works reliably.\r\n* **Parameter input modals** – close button functionality restored.\r\n* **Gateway reactivation warnings** eliminated through proper Pydantic model handling.\r\n* **SBOM generation** and documentation build targets now function correctly.\r\n* **Test suite stability** with comprehensive Pydantic pattern updates.\r\n\r\n## 🔐 Security\r\n\r\n* **Enhanced connection isolation** with proper file locking mechanisms.\r\n* **Improved error handling** that prevents information leakage.\r\n* **Database connection security** with retry policies that don't expose credentials.\r\n\r\n## 📦 Packaging & Deployment\r\n\r\n* **PyPI wheel improvements** with complete Alembic migration support.\r\n* **Container optimization** for better multi-instance deployments.\r\n* **Development tooling** enhancements for contributor onboarding.\r\n\r\n## 👥 New Contributors\r\n\r\n*We welcome new contributors who joined us in this release – thank you for your valuable contributions!*\r\n\r\n## 🙏 Returning Contributors who delivered excellence\r\n\r\n* **Mihai Criveti** – release management, database migration architecture, Go time server implementation, comprehensive testing and stability improvements.\r\n* **Keval Mahajan** – multi-server federation logic, UI picker implementation, auto-recovery system design.\r\n* **Madhav Kandukuri** – namespace design, connection export enhancements, developer experience improvements.\r\n* **Abdul Samad** – UI\u002FUX refinements, parameter modal fixes, visual consistency improvements.\r\n* **Manav Gupta** – packaging fixes, documentation improvements, build system enhancements.\r\n\r\n*Outstanding work making MCP Gateway production-ready!* 🎉\r\n\r\n---\r\n\r\n## 🔮 What's Next in v0.4.0\r\n\r\nThe next release will focus on **Bugfixes, Resilience & Code Quality** with:\r\n* Universa","2025-07-09T02:42:28",{"id":232,"version":233,"summary_zh":234,"released_at":235},135960,"v0.2.0","# 🚀 MCP Gateway v0.2.0 – 2025-06-24\r\n\r\nThis **feature-rich release** introduces a Streamable HTTP transport, `mcpgateway.translate` to convert `stdio` to `SSE`,  infrastructure-as-code assets, and a sleek dark-mode UI, while hardening stability and developer tooling across the board.\r\n\r\n## ✨ Highlights\r\n\r\n* 🌊 **First-class *Streamable HTTP* transport** – the gateway now speaks MCP’s new default protocol, with stateful-session & auth support. SSE still works, too. Introduced `mcpgateway.translate` to turn any `stdio` server into a `SSE` endpoint.\r\n* 🛠️ **Infra-as-Code** – drop-in **Terraform** modules & **Ansible** roles for cloud installs.  \r\n* ⚡ **Connection-string exporter** – one-click UI \u002F `\u002Fservers\u002F{id}\u002Fconnect` API for LangChain, Claude Desktop & friends.  \r\n* 🌒 **Dark-mode Admin UI** with a compact version-info panel.  \r\n* 🧑‍💻 **Developer experience overhaul** – 333 green unit tests, *tox*, pre-commit linters, coverage in CI, Python 3.11+.  \r\n* 🏗️ **Deployment goodies** – Helm charts accept external secrets\u002FRedis, Fly.io guide, Docker-compose switches.  \r\n* 🔒 **Security & hardening** – connection-level time-outs, CVE scans, dependency bumps.  \r\n\r\n## 🆕 Added\r\n\r\n* Streamable HTTP client\u002Fserver transport with Basic\u002FBearer auth & session persistence.  \r\n* Connection-string export API\u002FUI.  \r\n* Terraform modules & Ansible playbooks for cloud provisioning.  \r\n* Fast **Go** reference MCP server for benchmarking.  \r\n* Dark-mode theme, slimmer version-info widget, dev-onboarding checklist.  \r\n* *tox* config, pre-commit (ruff, flake8, yamllint), GH Actions **pytest + coverage**.  \r\n* Helm enhancements: external secrets\u002FRedis, walkthrough; Fly.io deployment guide.  \r\n\r\n## 🔄 Changed\r\n\r\n* **Python ≥ 3.11** (CI on Ubuntu 24.04 \u002F Python 3.12).  \r\n* Thorough Helm\u002FMakefile\u002FJWT helper refresh; tighter typing & linting; 333 unit tests now pass.  \r\n* Detailed context-merging algorithm notes added to docs.  \r\n\r\n## 🐛 Fixed\r\n\r\n* SBOM workflow & `make images\u002Fdocs` targets.  \r\n* GitHub Remote MCP server addition flow.  \r\n* REST path-parameter substitution, `PATCH` handling, 204 responses.  \r\n* Numerous flaky tests and mypy\u002Fflake8 violations.  \r\n\r\n## 🔐 Security\r\n\r\n* Dependency bumps, security-policy updates, CVE scans wired into pre-commit & CI.  \r\n\r\n## 📦 Packaging & Deployment\r\n\r\n* Helm charts accept external secrets & Redis.  \r\n* Docker-compose gains *local-image* switch; Fly.io guide.  \r\n* SBOM generation and license verification now reliable.  \r\n\r\n## 👥 New Contributors\r\n\r\n| Contributor              | First delivered in 0.2.0                                                          |\r\n|--------------------------|-----------------------------------------------------------------------------------|\r\n| **Abdul Samad**          | Dark-mode UI, compact version-info                                                |\r\n| **Arun Babu Neelicattu** | Raised minimum Python to 3.11                                                     |\r\n| **Manoj Jahgirdar**      | Docs home-page polish                                                             |\r\n| **Shoumi Mukherjee**     | Docs clean-ups & quick-start                                                      |\r\n| **Thong Bui**            | REST adapter path-params, `PATCH`, 204                                            |\r\n\r\n*Welcome aboard — your PRs made 0.2.0 shine!* 🎉  \r\n\r\n## 🙏 Returning Contributors who went the extra mile\r\n\r\n* **Mihai Criveti** – release mgmt, Helm refactor, full CI revamp, **333 green tests**, security & build updates, `mcpgateway.translate`.  \r\n* **Keval Mahajan** – implemented **Streamable HTTP** transport, UI transport column, gateway time-outs, test fixes.  \r\n* **Madhav Kandukuri** – ADRs for federation & UX, dark-mode polish, connection-string export spec, stability fixes.  \r\n* **Manav Gupta** – SBOM & license fixes, Makefile targets, Docker\u002FFly.io docs.  \r\n\r\n*Huge thanks for keeping the momentum going!* 🚀  \r\n\r\n---\r\n\r\n### 🔗 Resources\r\n\r\n* 📚 Docs: [https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F)  \r\n* 🐳 Container: `ghcr.io\u002Fibm\u002Fmcp-context-forge:v0.2.0`  \r\n* 🐍 PyPI: [`mcp-contextforge-gateway`](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-contextforge-gateway\u002F)  \r\n* 📈 Full changelog: [Compare v0.1.1…v0.2.0](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fcompare\u002Fv0.1.1...v0.2.0)\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n","2025-06-24T11:59:09",{"id":237,"version":238,"summary_zh":239,"released_at":240},135961,"v0.1.1","# 📦 MCP Gateway v0.1.1 – 2025‑06‑15\r\n\r\nThis is a **feature-packed minor release** focused on stability, packaging, wrapper enhancements, and documentation polish. It builds upon the initial public release (`v0.1.0`) by refining the developer experience and broadening deployment capabilities.\r\n\r\n## ✨ Highlights\r\n\r\n* 🔁 **New stdio-to-SSE wrapper** (`mcpgateway.wrapper`) that allows legacy MCP clients to interact with modern gateways\r\n* 📦 **Run as a Python module**: `python3 -m mcpgateway.wrapper` now supported thanks to package restructure\r\n* 🧪 **\u002Fready** endpoint for Kubernetes readiness probes\r\n* 🧬 **\u002Fversion** API and UI tab for runtime inspection\r\n* 🚀 **Helm charts**, improved Makefile and CI\u002FCD support\r\n* 📚 **Major documentation refresh**: Quick starts, pip install, Docker, FAQs, debugging tips, ArgoCD\r\n\r\n## 🆕 Added\r\n\r\n* New `mcpgateway.wrapper` with CLI and stdio support to connect to authenticated SSE gateways\r\n* `\u002Fversion` endpoint (also available via UI tab and CLI `--version`)\r\n* `\u002Fready` endpoint for Kubernetes readiness probes\r\n* New Helm charts and Kubernetes deployment assets\r\n* Improved CLI entry point via `mcpgateway` script (uses Uvicorn under the hood)\r\n* Python module now supports `python3 -m mcpgateway.wrapper` for stdio clients\r\n* Documentation updates: quoting advice for zsh, docker quick start, dev container, FAQ, GitHub review process, PyPi setup, ArgoCD\r\n* Makefile targets for ArgoCD\r\n* Initial `mcpgateway.translate` support to turn stdio -> SSE. More features & protocol translation options coming soon.\r\n\r\n## 🐛 Fixed\r\n\r\n* Fixed errors when deleting gateways with active metrics\r\n* Improved gateway addition logic when tools overlap — now adds missing tools without failure\r\n* Resolved basic authentication header bugs for tools and gateways\r\n* Captured detailed exceptions using `ExceptionGroup` support for better logs\r\n* Corrected static path resolution when installing as a wheel\r\n\r\n## 📦 Packaging & Deployment\r\n\r\n* Renamed PyPi package to avoid conflicts (`mcp-contextforge-gateway`)\r\n* Enhanced Makefile with `docker-run-ssl-host` and new publishing targets\r\n* Added VS Code Dev Container + GitHub Codespaces support\r\n* Added support for `APP_ROOT_PATH` when reverse proxying (e.g., behind `\u002Fgateway`)\r\n\r\n## 👥 New Contributors\r\n\r\n* @rakdutta, @MohanLaksh, @manavgup, @calculus-ask, @manojjahgirdar, @ryanmarc\r\n\r\n---\r\n\r\n### 🔗 Resources\r\n\r\n* 📚 Docs: [https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F](https:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F)\r\n* 🐳 Container: `ghcr.io\u002Fibm\u002Fmcp-context-forge:v0.1.1`\r\n* 🐍 PyPI: [`mcp-contextforge-gateway`](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-contextforge-gateway\u002F)\r\n* 📈 Full changelog: [Compare v0.1.0...v0.1.1](https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fcompare\u002Fv0.1.0...v0.1.1)\r\n","2025-06-15T19:12:31",{"id":242,"version":243,"summary_zh":244,"released_at":245},135962,"v0.1.0","## Overview\r\n\r\nInitial public release of **MCP Gateway** - a FastAPI-based gateway and federation layer for the Model Context Protocol (MCP).  \r\nThis preview delivers a fully-featured core, production-grade deployment assets and an opinionated developer experience.\r\n\r\n---\r\n\r\n### 🚪 Core protocol & gateway\r\n* 📡 **MCP protocol implementation** – initialise, ping, completion, sampling, JSON-RPC fallback  \r\n* 🌐 **Gateway layer** in front of multiple MCP servers with peer discovery & federation  \r\n\r\n### 🔄 Adaptation & transport\r\n* 🧩 **Virtual-server wrapper & REST-to-MCP adapter** with JSON-Schema validation, retry & rate-limit policies  \r\n* 🔌 **Multi-transport support** – HTTP\u002FJSON-RPC, WebSocket, Server-Sent Events and stdio  \r\n\r\n### 🖥️ User interface & security\r\n* 📊 **Web-based Admin UI** (HTMX + Alpine.js + Tailwind) with live metrics  \r\n* 🛡️ **JWT & HTTP-Basic authentication**, AES-encrypted credential storage, per-tool rate limits  \r\n\r\n### 📦 Packaging & deployment recipes\r\n* 🐳 **Container images** on GHCR, self-signed TLS recipe, health-check endpoint  \r\n* 🚀 **Deployment recipes** – Gunicorn config, Docker\u002FPodman\u002FCompose, Kubernetes, Helm, IBM Cloud Code Engine, AWS, Azure, Google Cloud Run  \r\n\r\n### 🛠️ Developer & CI tooling\r\n* 📝 **Comprehensive Makefile** (80 + targets), linting, > 400 tests, CI pipelines & badges  \r\n* ⚙️ **Dev & CI helpers** – hot-reload dev server, Ruff\u002FBlack\u002FMypy\u002FBandit, Trivy image scan, SBOM generation, SonarQube helpers  \r\n\r\n### 🗄️ Persistence & performance\r\n* 🐘 **SQLAlchemy ORM** with pluggable back-ends (SQLite default; PostgreSQL, MySQL, etc.)  \r\n* 🚦 **Fine-tuned connection pooling** (`DB_POOL_SIZE`, `DB_MAX_OVERFLOW`, `DB_POOL_RECYCLE`) for high-concurrency deployments  \r\n\r\n### 📈 Observability & metrics\r\n* 📜 **Structured JSON logs** and **\u002Fmetrics** endpoint with per-tool \u002F per-gateway counters  \r\n\r\n### 📚 Documentation\r\n* 🔗 **MkDocs site** – \u003Chttps:\u002F\u002Fibm.github.io\u002Fmcp-context-forge\u002F>\r\n\r\n---\r\n\r\n### Installation (container quick-start)\r\n\r\n```bash\r\ndocker run -d --name mcpgateway \\\r\n  -p 4444:4444 \\\r\n  -e HOST=0.0.0.0 \\\r\n  -e JWT_SECRET_KEY=my-test-key \\\r\n  -e BASIC_AUTH_USER=admin \\\r\n  -e BASIC_AUTH_PASSWORD=changeme \\\r\n  -e AUTH_REQUIRED=true \\\r\n  -e DATABASE_URL=sqlite:\u002F\u002F\u002F.\u002Fmcp.db \\\r\n  ghcr.io\u002Fibm\u002Fmcp-context-forge:v0.1.0\r\n```\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-context-forge\u002Fcommits\u002Fv0.1.0\r\n","2025-06-05T21:39:24"]