使用说明

解耦RAG MCP服务器：零延迟语义搜索架构

日期： 2026年3月
存储库： MCP服务器

1.执行摘要

高度优化的模型上下文协议（MCP）服务器，为Figma、Jira和Confluence提供零延迟语义RAG查询和统一集成。该架构将繁重的推理摄入管道与本地执行边缘完全解耦，提供轻量级的离线上下文检索，而无需依赖昂贵的基于云的AI API密钥。

主要建筑成就：

解决了通常与重型AI模型相关的内存不足（OOM）和延迟瓶颈。
设计了一种混合云本地拓扑，利用VPS进行繁重的工作，并利用本地边缘节点进行零延迟执行。
建立了一个强大的零信任安全网络管道。

2.架构与拓扑

该系统在战略上分为两个专业环境：

VPS Ingestor（重型起重设备）： 一个夜间cronjob管道，它抓取Atlassian数据（Jira/Confluence空间），分割文本，并使用开源代码生成向量嵌入 BAAI/bge-m3 通过3GB交换处理。输出存储在集中式ChromaDB中。
本地边缘服务器（零延迟）： 基于macOS的本地FastMCP服务器，通过以下方式获取差异ChromaDB更新 rsync它使用本地计算资源即时处理RAG查询。

2.1上下文关系图

graph TD
    User((Local User))
    Antigravity(AI Assistant)
    RAG_System[Decoupled RAG System]
    Atlassian[(Atlassian Cloud)]
    HuggingFace[(HuggingFace Models Hub)]

    User -->|Chat / Request Analysis| Antigravity
    Antigravity -->|Invoke tools via MCP| RAG_System
    RAG_System -->|Schedule scraping| Atlassian
    RAG_System -->|Download BAAI/bge-m3| HuggingFace

2.2集装箱示意图

graph TB
    subgraph "VPS Environment (Ubuntu Server)"
        Cron[Cronjob Scheduler]
        Ingestor[Python Ingestor Script]
        HF_Model_VPS[HuggingFace Model]
        DB_VPS[(ChromaDB Vector Database)]
        
        Cron -->|Trigger 1:00 AM| Ingestor
        Ingestor -->|Init & Embed Text| HF_Model_VPS
        Ingestor -->|Save Vectors| DB_VPS
    end

    subgraph "Local Environment (macOS Edge)"
        SyncAgent[macOS LaunchAgent]
        DB_Local[(ChromaDB Local Mirror)]
        MCP_Server[Python FastMCP Server]
        HF_Model_Local[HuggingFace Model]
        
        SyncAgent -->|Rsync Pull| DB_VPS
        SyncAgent -->|Update| DB_Local
        MCP_Server -->|Read Vectors| DB_Local
        MCP_Server -->|Embed User Query| HF_Model_Local
    end

    Atlassian_Ext([Atlassian API]) -->|Fetch Data| Ingestor
    LLM_Client([LLM Client]) <-->|stdio / MCP Protocol| MCP_Server

2.2.1.VPS环境（云数据摄取器）

VPS子系统充当重型起重节点。它自动提取原始数据源并将其转换为Vector数据库。

Cronjob调度程序： 系统调度器（cron）负责在以下位置触发提取、转换、加载（ETL）管道 1:00 AM 每天，在非高峰时段优化带宽。
Python Ingestor脚本： 提取模块直接与 大西洋API 聚合来自Jira和Confluence平台的文档（PRD、Epics、用户故事）。然后对数据进行预处理，包括净化和分块。
拥抱人脸嵌入模型： 自然语言处理（NLP）分析层。该过程利用了高度优化的多语言 BAAI/bge-m3 嵌入模型，将文本编码并转换为向量语义空间。
ChromaDB矢量数据库： 存储输出的主矢量数据库。在这个阶段，ChromaDB严格以写优化的角色运行，以保持原始数据的完整性。

2.2.2.本地环境（macOS边缘节点）

本地子系统将用户的端点转换为推理边缘节点，确保绝对的数据隐私和零延迟查询。

macOS启动代理： 配置为自动同步过程的后台守护进程。每4小时，系统触发 rsync 协议，用于将矢量数据库的差异文件（增量变化）从VPS服务器下载到本地工作站。
ChromaDB本地镜像： 数据库的完全独立的本地副本。这种架构消除了远程网络I/O，最大限度地提高了上下文检索速度。
Python FastMCP服务器： 端点的核心通信接口，遵循模型上下文协议（MCP）标准。
- LLM生成的查询矢量化过程完全在本地Mac上使用 HuggingFace (BAAI/bge-m3) 模块。
- 它对以下对象执行相似性搜索 本地镜像数据库 提取相关上下文。
LLM客户： 临时AI集成（例如，Cursor AI、Claude Desktop）。该应用程序直接连接到FastMCP提供的Context Tool，在本地处理器上本地执行业务逻辑分析，确保企业数据结构零泄漏到外部网络。

2.2.3.架构的核心优势

成本与性能优化： 复杂的计算开销（降噪、嵌入API成本）被完全卸载到VPS。
最大隐私： 边缘推理管道使LLM能够查询Atlassian数据库，而不会将内部业务安全、商业秘密或敏感工件暴露给公共云，从而巩固了可持续的安全循环。

3.数据流和请求生命周期

3.1夜间数据同步和摄入管道

sequenceDiagram
    autonumber
    participant Mac as Local Edge (SyncAgent)
    participant VPS as Cloud Ingestor (VPS)
    participant Model as HuggingFace (bge-m3)
    participant Atlas as Atlassian (DataSource)
    
    VPS->>Atlas: Request pages/issues from Spaces
    Atlas-->>VPS: Return Raw HTML / JSON Payload
    Note over VPS: Chunking & Pre-processing
    VPS->>Model: Initialize BAAI/bge-m3 Engine
    Note over VPS: Vectorization Matrix Generation
    VPS->>VPS: Persist Vectors to ChromaDB
    
    loop Background Sync (Every 4 Hours)
        Mac->>VPS: Initiate SSH Rsync
        VPS-->>Mac: Transmit incremental delta
        Mac->>Mac: Merge local ChromaDB store
    end

3.2实时边缘RAG查询

sequenceDiagram
    autonumber
    actor User as Local User
    participant AI as AI Agent (LLM)
    participant MCP as Python FastMCP Server
    participant LB_Model as Local Model Wrapper
    participant DB as Local ChromaDB Engine
    
    User->>AI: "Search PRD for Notification Feature"
    Note over AI: Detects Intent -> Routes via MCP
    AI->>MCP: Execute tool: search_agile_docs
    MCP->>LB_Model: Vectorize query string
    LB_Model-->>MCP: Yield Query Matrix
    MCP->>DB: Cosine Similarity Execution
    DB-->>MCP: Retrieve Top-K Context Vectors
    MCP-->>AI: Dispatch Markdown Context w/ Citations
    Note over AI: Contextual Synthesis
    AI-->>User: Synthesized response based on internal docs

4.技术栈、模块化和安全性

该系统基于现代人工智能堆栈构建，其组织结构清晰地描绘了来自本地执行服务的重云摄取机制，并在每一层都进行了安全设计。

4.1系统模块化

vps-ingestor/rag_pipeline.py （重型起重）： 处理VPS上的预定数据提取和计算密集型矢量化。
local-rag-mcp/server.py （本地执行）： macOS边缘的低占用FastMCP监听器和相似性执行块。
local-rag-mcp/sync.sh （自动化）： LaunchAgent可执行文件自动执行差异复制，无需用户干预。

配置注入

"jira-confluence-rag": {
  "command": "/path/to/MCP-server/local-rag-mcp/venv/bin/python",
  "args": ["/path/to/MCP-server/local-rag-mcp/server.py"]
}

4.2技术栈

核心与人工智能： Python 3.x、FastMCP协议、HuggingFace(sentence-transformers, BAAI/bge-m3)，ChromaDB。
基础设施： Ubuntu服务器、macOS、Unix Cron、macOS LaunchAgents。
安全和网络： Tailscale（VPN）、SSH上的Rsync、UFW（非复杂防火墙）。

4.3零信任安全态势

全系统安全可防止未经授权的访问，并在传输过程中保护敏感的企业数据：

Tailscale Mesh VPN： 流量仅在VPS和边缘节点之间的私有加密覆盖网络中运行。
严格的UFW防火墙： 公共SSH（端口22）和外部向量被阻止；同步完全依赖于安全 tailscale0 界面。
基于证书的自动化： VPS上的密码身份验证已完全禁用。无人值守 sync-db.sh 工艺使用硬化 id_ed25519 钥匙。

作为高级AI编排、上下文工程和解耦系统设计的技术展示而开发。

5.AI同事（唐·BSA·盖茨时间线）

flowchart TD
    classDef gate fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#01579b,font-weight:bold
    classDef cmd fill:#e8f5e9,stroke:#4caf50,stroke-width:1px,color:#2e7d32
    classDef proof fill:#ffebee,stroke:#f44336,stroke-width:1px,color:#c62828
    classDef owner fill:#fff8e1,stroke:#ffc107,stroke-width:1px,color:#f57f17
    classDef note fill:#fbe9e7,stroke:#ff8a65,stroke-width:1px,stroke-dasharray: 5 5,color:#bf360c

    subgraph "DON BSA Gates Timeline"
        G1["GATE 01<br>BRAINSTORMED"]:::gate
        G2["GATE 02<br>ELICITED"]:::gate
        G3["GATE 03<br>PRD_READY"]:::gate
        G4["GATE 04<br>BROKEN_DOWN"]:::gate
        G5["GATE 05<br>DESIGNED"]:::gate
        G6["GATE 06<br>DESIGN_VERIFIED"]:::gate

        G1 --> G2
        G2 --> G3
        G3 --> G4
        G4 --> G5
        G5 --> G6
    end

    %% G1 Details
    C1("don.brainstorm"):::cmd
    P1("problem-frame.md"):::proof
    O1("Owner: John / Don"):::owner
    G1 -.-> C1 -.-> P1 -.-> O1

    %% G2 Details
    C2("don.elicit"):::cmd
    P2("elicitation-log.md"):::proof
    O2("Owner: Mary / Don"):::owner
    G2 -.-> C2 -.-> P2 -.-> O2

    %% G3 Details
    C3("don.prd / don.validate-prd"):::cmd
    P3("prd.md + verify-prd.md"):::proof
    O3("Owner: John / Mary / Don"):::owner
    G3 -.-> C3 -.-> P3 -.-> O3

    %% FORK POST GATE 03
    subgraph "Post-Gate 03 Fork (Enrichment)"
        F_ARCH["don.architecture<br>architecture.md"]:::cmd
        F_UX["don.ux<br>ux-design-specification.md"]:::cmd
    end
    
    G3 -.-> F_ARCH
    G3 -.-> F_UX
    
    F_NOTE1("Design blocked if missing architecture.md"):::note
    F_NOTE2("Design blocked if missing ux-design-specification.md"):::note
    
    F_ARCH -.-> F_NOTE1 -.-> G5
    F_UX -.-> F_NOTE2 -.-> G5

    %% G4 Details
    C4("don.breakdown"):::cmd
    P4("epics.md"):::proof
    O4("Owner: Mary / Don"):::owner
    G4 -.-> C4 -.-> P4 -.-> O4

    %% G5 Details
    C5("don.design"):::cmd
    P5("artifact/solution-scope.yml"):::proof
    O5("Owner: Sally / Don"):::owner
    G5 -.-> C5 -.-> P5 -.-> O5

    %% G6 Details
    C6("don.verify-solution"):::cmd
    P6("verification bundle"):::proof
    O6("Owner: Sally / Don"):::owner
    G6 -.-> C6 -.-> P6 -.-> O6

6.绩效评估：RAG+工作流与直接搜索

下表比较了使用即席直接搜索（直接搜索/单一技能）与将语义搜索与自动化工作流相结合的集成模型（RAG+工作流）时的系统性能。

评估标准	直接搜索/单项技能	RAG+工作流程（MCP服务器）
任务完成速度和上下文精度	中等。严重依赖精确的关键字匹配。	非常高。使用文本嵌入（向量相似性）来捕获精确的上下文。
模糊查询和精度	低。容易失败或返回没有确切关键字的无关文档。	高。理解语义意图，并自动将抽象概念映射到相关文档。
自动化率	~30%-40%（人类必须手动过滤、连锁信息并不断切换技能）。	~85% - 90% （上下文从Atlassian平滑地自动注入到分析管道中）。
开发时间（工时）	低（使用现成的工具，没有硬件/软件集成开销）。	高最初（VPS Ingestor、ChromaDB、Edge节点、Tailscale的设置）。
劳动力套利	低-中（仅减轻零星的手动查找任务）。	非常高（取代初级/中级BA的大部分文件和综合工作量）。
执行错误率	高。由于上下文中断而导致文件丢失或人工智能幻觉的风险。	低。将数据分割成精确的小块（Top-K），以尽量减少噪声。
人在回路频率	持续（人类必须不断地提示和逐步审查）。	稀疏。干预主要发生在战略批准“盖茨”（证明审查）。
代币消费	高（浪费令牌重新加载冗余上下文或复制粘贴整个页面）。	优化（只检索和注入包含所需内容的Top-K小块）。

6.1投资回报率计算公式（投资回报率）

MCP服务器RAG架构的盈利能力使用以下公式进行评估：

$$投资回报率=\sum（T\times C）+\Delta R-（D+O）}$$

哪里：

T：节省的时间（以小时为单位）。
C：平均人工成本（$/h）。
$\Delta R$：更快的处理速度带来的额外收入（例如，更顺畅的工作流程导致更快的发布）。
D：MCP服务器的开发和部署成本（资本支出）。
哦：云VPS服务器、LLM代币等运营成本。（运营支出）。