AI-infrastructure

人工智能基础设施

人工智能工具、MCP服务器、网关和平台服务的中央基础设施。

待办事项

• \[\]创建一个 ai-infrastructure 技能（in ~/AI/skills/ 或者在这个仓库中）记录所有服务、端口、启动命令和依赖关系，以便AI代理在设置机器或调试连接问题时知道哪些基础设施可用。

建筑

@startuml ai-infrastructure
!theme plain
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
skinparam defaultFontName Consolas

title AI Infrastructure Architecture

' === AI Clients ===
package "AI Clients" as clients #E3F2FD {
  [Claude Code] as claude_code
  [VS Code Copilot] as vscode
  [Claude Desktop] as claude
  [Cline / Other] as other
}

' === LLM Proxy (standalone, implicit default network) ===
package "Context Lens (implicit network)" as cl_stack #E0F7FA {
  component "context-lens\n:4040 (reverse proxy)\n:4041 (web UI + ingest API)" as context_lens #80DEEA
  component "mitmproxy\n:8080 (HTTPS forward proxy)" as mitmproxy #4DD0E1
}

' === Gateway Stacks (each has private default + ai-shared) ===
package "agentgateway stack (private + ai-shared)" as ag_stack #E8F5E9 {
  component "agentgateway\n:3847 (MCP)\n:15001 (Admin UI)\n:15020 (Metrics)" as agentgateway #C8E6C9
  component "nginx-proxy\n:3443 (HTTPS)\n:9223 (CDP proxy)" as ag_nginx #A5D6A7
  component "stdio-proxy (included)\nseq-thinking, azure-devops" as ag_stdio #81C784
}

package "mcpx stack (private + ai-shared)" as mcpx_stack #E8F5E9 {
  component "mcpx (Lunar.dev)\n:9000 (MCP)\n:5173 (Control Plane)" as mcpx #C8E6C9
  component "nginx-ssl\n:9443 (HTTPS MCP)\n:5443 (HTTPS UI)\n:9222 (CDP)\n:61822 (Kapture WS)" as mcpx_nginx #A5D6A7
  component "stdio-proxy (included)\nseq-thinking, kapture" as mcpx_stdio #81C784
  component "lunar-proxy\n:8000 (rate limiting)\n(not actively routed)" as lunar #E0E0E0
}

' === Shared MCPs (ai-shared network) ===
package "Shared MCPs (ai-shared)" as shared_mcps #FFF3E0 {
  [context7\n:7008] as context7 #FFCC80
  [qdrant-mcp\n:7020] as qdrant_mcp #FFCC80
  [memory\n:7040 (singleton)] as memory #FFCC80
  [playwright\n:7007] as playwright #FFE0B2
  [browser-use\n:7011] as browser_use #FFE0B2
  [hass-mcp\n:7010] as hass_mcp #FFE0B2
}

' === Backing Services ===
package "Backing Services (ai-shared)" as backing #F3E5F5 {
  [Qdrant\n:6333 (HTTP)\n:6334 (gRPC)] as qdrant #CE93D8
  [Langfuse\n:3100 (UI)] as langfuse #CE93D8
  [Watchtower\n(auto-update)] as watchtower #E1BEE7
}

' === Observability ===
package "Observability (ai-shared)" as observability #E1F5FE {
  component "OTel Collector\n:4317/:4318 (internal)" as otel #81D4FA
  component "Jaeger\n:16686 (UI)" as jaeger #4FC3F7
  component "Prometheus\n:9090" as prometheus #29B6F6
  component "Grafana\n:3000" as grafana #03A9F4
}

' === Connections ===
' Clients to Context Lens
claude_code --> context_lens : ANTHROPIC_BASE_URL\n:4040
vscode --> mitmproxy : HTTPS_PROXY\n:8080
mitmproxy --> context_lens : POST /api/ingest\n:4041

' Clients to Gateways
claude_code --> agentgateway : MCP :3847\nx-client-id
claude --> mcpx : MCP :9000
other --> ag_nginx : HTTPS :3443

' TLS proxies
ag_nginx --> agentgateway : reverse proxy
mcpx_nginx --> mcpx : reverse proxy

' Gateways to private stdio-proxies
agentgateway --> ag_stdio : private network
mcpx --> mcpx_stdio : private network

' Gateways to shared MCPs (via ai-shared)
agentgateway --> context7 : SSE (ai-shared)
agentgateway --> qdrant_mcp : SSE
agentgateway --> memory : SSE
mcpx --> context7 : SSE (ai-shared)
mcpx --> qdrant_mcp : SSE
mcpx --> memory : SSE

' Backing
qdrant_mcp --> qdrant : :6333

' Observability
agentgateway --> otel : OTLP traces
otel --> jaeger : traces
otel --> prometheus : span metrics
grafana --> prometheus : query
grafana --> jaeger : query

' Legend
legend right
  |= Color |= Layer |
  |  | LLM Proxy (standalone) |
  |  | Gateway |
  |  | TLS Termination |
  |  | stdio-proxy (per-stack) |
  |  | Shared MCP (running) |
  |  | Shared MCP (available) |
  |  | Backing Service |
  |  | Observability |
  |  | Inactive |
endlegend

@enduml

当前状态

组合堆叠

每个堆栈都是独立的 docker compose 单位。带有stdio代理的堆栈将其包含在共享模板中(mcps/stdio-proxy/)--每个都在专用网络上获得自己的实例，以避免DNS冲突。

代理网关 (gateways/agentgateway/)--Linux基金会MCP网关

mcpx (mcps/mcpx/)--Lunar.dev MCP网关，带有工具组和每个客户端的访问控制

上下文镜头 (platform/context-lens/)-LLM API流量拦截和上下文窗口分析

矢量点 (mcps/qdrant-mcp/)——矢量数据库和语义搜索MCP

共享MCP（ai共享网络）

这些作为独立容器运行，两个网关都可以通过 ai-shared 网络。

平台服务

网络体系结构

Docker网络

两个网关服务（agentgateway、mcpx）都加入 二 网络：它们的堆栈是私有的 default （访问自己的stdio代理）和 ai-shared （达到共享MCP）。这就是为什么stdio代理被包含为一个组合模板，而不是作为一个共享服务运行的原因——每个堆栈在自己的网络上都有自己的实例。

内部Docker流量（ai共享）

|从|到|港口|目的| | ---- | -- | ---- | ------- | |agentgateway/mcpx|context7_mcp|7008|库文档mcp| |agentgateway/mcpx|qdrant-mcp|7020|语义搜索mcp| |agentgateway/mcpx|memory_mcp|7040|知识图mcp（单例）| |agentgateway/mcpx|stdio代理（自有堆栈）|7030|stdio MCP（专用网络）| |qdrant-mcp|qdrant|6333|矢量数据库查询| |agentgateway |酒店收集器|4317|OTLP跟踪| |酒店收藏家|耶格尔| 14317 |微量出口| |otel收集器|（自己）|8889|跨度指标| |prometheus |代理网关|15020|指标抓取| |普罗米修斯|酒店收藏家|8889|跨度指标刮擦| |grafana|prometheus|9090|指标查询| |grafana | jaeger | 16686 |跟踪查询| |mitmproxy|context-tlens|4041|POST捕获以摄取API|

目录结构

ai-infrastructure/
├── clients/           # AI client configurations
│   ├── claude/        # Claude Desktop config
│   ├── cline/         # Cline config
│   └── copilot/       # VS Code Copilot config
├── gateways/          # MCP gateways
│   └── agentgateway/  # Linux Foundation MCP gateway
├── mcps/              # MCP servers
│   ├── browser-use/   # AI browser automation
│   ├── context7/      # Library documentation
│   ├── hass-mcp/      # Home Assistant
│   ├── kapture/       # Chrome extension MCP
│   ├── mcpx/          # MCPX gateway (alternative)
│   ├── memory/        # Memory/knowledge graph
│   ├── playwright/    # Playwright browser automation
│   ├── qdrant-mcp/    # Qdrant semantic search (mcp-proxy + mcp-server-qdrant)
│   ├── sequential-thinking/ # Chain of thought reasoning
│   └── stdio-proxy/   # stdio→SSE bridge
├── platform/          # Platform services
│   ├── context-lens/  # LLM context window inspector
│   ├── langfuse/      # LLM observability, prompts, evals
│   └── observability/ # Prometheus, Grafana, Jaeger
└── workflows/         # Custom workflow definitions

组件

网关

MCP服务器

独立的MCP在上作为自己的容器运行 ai-shared.stdio MCP在每堆栈stdio代理实例内运行。

平台服务

客户

看 客户端/readme.md 用于配置。

快速开始

1.创建共享Docker网络

docker network create ai-shared

备注：The ai-shared 网络是由定义它的第一个堆栈创建的。只有当您想以不同的顺序启动堆栈时，才需要执行此步骤。

2.启动mcpx网关

cd mcps/mcpx
cp .env.example .env   # Edit: set MCP_CONFIG, optionally CUSTOM_CA_CERT
docker compose up -d

3.启动代理网关

cd gateways/agentgateway
docker compose up -d

4.启动Qdrant+语义搜索MCP

cd mcps/qdrant-mcp
docker compose up -d

5.启动上下文镜头（LLM流量分析）

cd platform/context-lens
docker compose up -d

然后设置 ANTHROPIC_BASE_URL=http://127.0.0.1:4040/claude 在您的shell配置文件或VS代码设置中。看 上下文镜头自述 对于每个客户端的设置。

6.启动可观测性堆栈（可选）

cd platform/observability
docker compose up -d

7.启动Langfuse（可选）

cd platform/langfuse
docker compose up -d

8.访问

9.配置您的AI客户端

看 客户/ 用于每个AI客户端的配置示例。

港口

代理网关堆栈

mcpx堆栈

上下文镜头堆栈

共享MCP和支持服务

可观察性和平台（运行时）

可观测性

可观测性堆栈提供度量、跟踪和可视化：

跟踪流量：

agentgateway → OTel Collector → Jaeger (traces)
                             → Prometheus (span metrics)

指标包括：

• agentgateway_requests_total -按客户端、方法、状态列出的HTTP请求
• agentgateway_mcp_requests -MCP工具调用
• tool_calls_total -按服务器和工具名称调用工具
• list_calls_total -列出操作
• 来自OTel Collector的跨度衍生指标（延迟直方图、呼叫计数）

待办事项

• \[\]修复langfuse提示MCP后端-langfuse堆栈（：3101）未运行的问题；当无法访问此上游时，agentgateway无法初始化。需要确保langfuse从网关开始或优雅地处理。
• \[\]修复黑曜石MCP后端-黑曜岩语义插件（：3001）未运行；与langfuse相同的问题。需要自动启动或使网关容忍缺少可选后端。
• \[\]使用agentgateway的原生TLS而不是nginx代理进行HTTPS终止评估
• \[\]使用CDP代理配置Playwright MCP（浏览器使用MCP连接到主机Chrome需要9223上的nginx代理）
• \[\]使用Watchtower标签（代理网关、剧作家、qdrant、可观察性堆栈）重新创建剩余的容器——添加标签以组成文件，但容器需要 docker compose up -d --force-recreate 把它们捡起来
• \[x\] 为每个客户端跟踪添加客户端标识标头
• \[x\] 设置Jaeger进行分布式跟踪
• \[x\] 配置代理网关以向OpenTetry收集器发送跟踪
• \[x\] 创建Grafana仪表板以实现指标可视化
• \[x\] 建立Langfuse以实现LLM的可观察性和及时管理

工作流

叉子贡献：樱桃采摘阶段性变化

用于为上游开源项目（如Context Lens）做出贡献。维护本地 main 所有正在进行的修复都已应用，而每个修复都作为单独的上游PR存在于自己的分支上。

upstream/main ← PRs from your fork branches
    ↑
origin/main (your fork, tracks upstream)
    ↑
local main (staged cherry-picks from all active branches)
    ↑
┌───┴───┬──────────┬──────────┐
fix/a   fix/b   feat/c   fix/d    ← worktree branches, each = 1 PR

密钥不变量：本地 main 从未提前承诺 origin/main.所有仅限本地的更改都以 上演但未确定 樱桃采摘。

开发 在工作台分支上（每个分支=一个PR）：

git worktree add ../repo-fix-foo fix/foo
cd ../repo-fix-foo
# ... make changes, commit, push ...
git push origin fix/foo   # open PR against upstream/main

堆栈 本地主干道的变化：

git checkout main
git cherry-pick --no-commit origin/main..

# Repeat for each active branch — all fixes are now applied but uncommitted

同步 与上游（链：上游→ 起源/主要→ 分支机构）：

git stash push -m "staged cherry-picks"
git checkout main && git fetch --all
git rebase upstream/main
git push origin main                    # --force-with-lease if rebased

# Rebase active branches onto synced main
git rebase main fix/still-open-a
git push --force-with-lease origin fix/still-open-a

# Rebuild staged state from remaining open branches
git checkout main
git cherry-pick --no-commit origin/main..fix/still-open-a
git stash drop

交换机 --克隆叉子，取，樱桃采摘打开的树枝：

git clone  && cd repo
git remote add upstream 
git fetch --all && git rebase upstream/main
git cherry-pick --no-commit origin/main..origin/fix/branch-a
git cherry-pick --no-commit origin/main..origin/fix/branch-b

提示:

• git branch --no-merged origin/main --列出仍需采摘的树枝
• git diff --cached --stat --查看您当前的樱桃采摘堆栈
• git restore --staged . --如果阶段状态变得混乱，则中止并重建

看 上下文镜头工作流程详细信息 用于项目特定的分支状态和机器恢复配方。

平台特定设置

• 视窗 --WSL仓库位置、跨文件系统陷阱、SSH密钥、Docker桌面细节

资源

• 模型上下文协议
• 代理网关
• agentgateway可观察性
• 浪焰
• mcpx/Lunar.dev
• 上下文镜头