Nexla Doc MCP

Nexla文件MCP

一种模型上下文协议（MCP）服务器，允许AI代理对PDF文档提出自然语言问题，并通过检索增强生成（RAG）接收基于源的答案。

______________________________________________________________________

目录

• 架构概述
• 安装说明
• 码头工人
• 配置
• MCP工具文档
• 交互日志示例
• 设计决策与权衡
• Vibe编码：人工智能辅助开发
• 许可证

______________________________________________________________________

架构概述

                              ┌──────────────────────┐
                              │     MCP Client       │
                              │  (Claude Desktop /   │
                              │   ChatGPT / Agent)   │
                              └──────────┬───────────┘
                                         │ stdio / SSE
                                         ▼
                    ┌────────────────────────────────────────────┐
                    │        FastMCP Server  (server.py)         │
                    │                                            │
                    │  ┌──────────────┐   ┌───────────────────┐  │
                    │  │ query_       │   │ list_documents    │  │
                    │  │ documents    │   │                   │  │
                    │  └──────────────┘   └───────────────────┘  │
                    │  ┌──────────────┐   ┌───────────────────┐  │
                    │  │ reingest_    │   │ get_document_     │  │
                    │  │ documents    │   │ summary           │  │
                    │  └──────────────┘   └───────────────────┘  │
                    └───────────┬──────────────────┬─────────────┘
                                │                  │
                  ┌─────────────▼───┐      ┌───────▼──────────────┐
                  │   Ingestion     │      │   Retrieval Layer    │
                  │   Pipeline      │      │   (retrieval.py)     │
                  │ (ingestion.py)  │      │                      │
                  └──┬──────────────┘      └──┬────────────────┬──┘
                     │                        │                │
               ┌─────▼──────┐         ┌──────▼──────┐  ┌──────▼──────────┐
               │ pdfplumber │         │  ChromaDB   │  │  LLM Provider  │
               │ (PDF text  │         │  (vectors + │  │  (OpenAI /     │
               │  extract)  │         │  embeddings)│  │   Anthropic)   │
               └────────────┘         └─────────────┘  └────────────────┘

               ┌─────────────────────────────────────────────────────────┐
               │                     data/ (PDFs)                        │
               │  Mounted from host filesystem or Docker volume          │
               └─────────────────────────────────────────────────────────┘

组件责任

______________________________________________________________________

安装说明

先决条件

• Python 3.10或更高版本
• OpenAI API密钥（或Anthropic API密钥，如果切换提供商）

1.克隆并进入项目

git clone 
cd nexla-doc-mcp

2.创建虚拟环境

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows

3.安装依赖项

pip install -r requirements.txt

4.配置环境

cp .env.example .env

编辑 .env 并添加您的API密钥：

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

5.添加PDF文档

将您要查询的任何PDF文件放入 data/ 目录：

cp ~/Documents/my-report.pdf data/

6.运行服务器

python main.py

服务器在第一次运行时自动接收所有PDF，然后通过stdio监听MCP连接。

Claude桌面配置

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "nexla-doc-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/nexla-doc-mcp/main.py"],
      "env": {
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

保存后重新启动Claude Desktop。工具将出现在工具菜单中（锤子图标）。

______________________________________________________________________

码头工人

使用Docker Compose构建和运行

cp .env.example .env
# Edit .env with your OPENAI_API_KEY
# Place PDFs in data/

docker compose up --build

服务器在容器内启动，自动从装载的文件中摄取PDF data/ 卷，并将ChromaDB索引持久化在一个命名的Docker卷中(chroma_data).

使用普通Docker运行

docker build -t nexla-doc-mcp .

docker run --rm -it \
  -e LLM_PROVIDER=openai \
  -e OPENAI_API_KEY=sk-... \
  -v "$(pwd)/data:/app/data" \
  nexla-doc-mcp

Claude桌面与Docker

{
  "mcpServers": {
    "nexla-doc-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "LLM_PROVIDER=openai",
        "-e", "OPENAI_API_KEY=sk-...",
        "-v", "/absolute/path/to/data:/app/data",
        "nexla-doc-mcp"
      ]
    }
  }
}

______________________________________________________________________

配置

所有设置均在中定义 src/config.py 并且可以通过环境变量进行覆盖。

______________________________________________________________________

MCP工具文档

1. query_documents

问一个关于你的索引PDF文档的自然语言问题。

输入示例：

{
  "question": "What are the main data integration patterns described in the document?",
  "top_k": 5
}

输出示例：

{
  "answer": "The document describes three main data integration patterns: batch ETL, real-time streaming, and change data capture (CDC). Batch ETL is recommended for large historical loads [Source: integration-guide.pdf, Page 12], while streaming is preferred for low-latency use cases [Source: integration-guide.pdf, Page 15]. CDC provides an efficient middle ground by capturing only changed records [Source: integration-guide.pdf, Page 18].",
  "sources": [
    {"document": "integration-guide.pdf", "page": 12, "relevance_score": 0.8432},
    {"document": "integration-guide.pdf", "page": 15, "relevance_score": 0.7891},
    {"document": "integration-guide.pdf", "page": 18, "relevance_score": 0.7654}
  ],
  "chunks_used": 3
}

2. list_documents

列出所有带有元数据的索引PDF文档。

输出示例：

[
  {
    "document": "integration-guide.pdf",
    "pages": 24,
    "chunks": 47,
    "file_hash": "a1b2c3d4e5f6..."
  }
]

3. reingest_documents

强制重新摄取中的所有PDF data/ 目录（清除并重建索引）。

输出示例：

{
  "status": "complete",
  "documents_processed": 2,
  "documents_ingested": 2,
  "details": [
    {"document": "report.pdf", "status": "ingested", "pages": 10, "chunks": 22},
    {"document": "guide.pdf", "status": "ingested", "pages": 5, "chunks": 11}
  ]
}

4. get_document_summary

获取特定索引文档的摘要和元数据预览。

输出示例：

{
  "document": "report.pdf",
  "total_pages": 10,
  "total_chunks": 22,
  "file_hash": "a1b2c3d4...",
  "preview": "Executive Summary\n\nThis report presents an analysis of data pipeline architectures..."
}

______________________________________________________________________

交互日志示例

以下是通过运行 query_documents Docker中的工具针对5个索引PDF（总共72个块）：

示例1：单文档事实问题

问题： *“什么是Nexset，它在Nexla平台上是如何工作的？”*

{
  "answer": "A Nexset is a core abstraction in the Nexla platform, described as a self-describing, portable data unit that encapsulates schema, metadata, and transformation logic. It allows data engineers and analysts to treat data products as composable building blocks rather than brittle pipelines. Nexsets facilitate the creation, management, and monitoring of data flows across disparate systems without the need for writing custom ETL code [Source: nexla-platform-overview.pdf, Page 1].",
  "sources": [
    { "document": "nexla-platform-overview.pdf", "page": 1, "relevance_score": 0.5392 },
    { "document": "nexla-platform-overview.pdf", "page": 1, "relevance_score": 0.4043 },
    { "document": "data-engineering-best-practices.pdf", "page": 4, "relevance_score": 0.2509 },
    { "document": "data-security-compliance-guide.pdf", "page": 3, "relevance_score": 0.2201 },
    { "document": "nexla-platform-overview.pdf", "page": 2, "relevance_score": 0.1367 }
  ],
  "chunks_used": 5
}

示例2：跨文档比较

问题： *“比较文档中描述的数据管道编排和工作流管理方法。”*

{
  "answer": "The documents describe several approaches to data pipeline orchestration and workflow management:\n\n1. **Apache Airflow**: It is the most popular orchestrator for batch data pipelines, used by major companies like Airbnb, Google, and PayPal. Airflow DAGs (Directed Acyclic Graphs) define task dependencies, scheduling, and retry behavior. Managed offerings include Google Cloud Composer, Amazon MWAA, and Astronomer [Source: data-engineering-best-practices.pdf, Page 4].\n\n2. **Prefect and Dagster**: These are modern alternatives to Airflow. Prefect emphasizes a Pythonic API and dynamic workflows, while Dagster introduces software-defined assets for more intuitive data lineage and dependency management [Source: data-engineering-best-practices.pdf, Page 4].\n\n3. **Event-driven architectures**: In these architectures, orchestration is often replaced by choreography, where each service reacts to events independently without a central coordinator. This pattern is compatible with tools like Kafka and cloud event buses such as AWS EventBridge and Google Eventarc, but it requires careful attention to failure handling and observability [Source: data-engineering-best-practices.pdf, Page 4].\n\n4. **Nexla's Flow Engine**: This provides built-in orchestration that can eliminate the need for a separate orchestrator in many use cases. It supports scheduling, retry logic, and exactly-once delivery semantics. Dependencies between flows are managed through Nexset lineage tracking [Source: nexla-platform-overview.pdf, Page 2].\n\nEach approach has its strengths, with Airflow being widely adopted for its robust DAG-based orchestration, Prefect and Dagster offering modern features for dynamic workflows and intuitive management, event-driven architectures providing decentralized orchestration, and Nexla's Flow Engine offering integrated orchestration with advanced features like exactly-once delivery.",
  "sources": [
    { "document": "data-engineering-best-practices.pdf", "page": 4, "relevance_score": 0.4304 },
    { "document": "data-engineering-best-practices.pdf", "page": 1, "relevance_score": 0.2434 },
    { "document": "data-engineering-best-practices.pdf", "page": 4, "relevance_score": 0.101 },
    { "document": "ai-ml-pipeline-architecture.pdf", "page": 1, "relevance_score": -0.0014 },
    { "document": "nexla-platform-overview.pdf", "page": 2, "relevance_score": -0.0403 }
  ],
  "chunks_used": 5
}

示例3：特定细节提取

问题： *“所有文件中都提到了哪些公司和组织？”*

{
  "answer": "The companies and organizations mentioned across the documents are:\n\n1. Alation [Source: data-engineering-best-practices.pdf, Page 5]\n2. Collibra [Source: data-engineering-best-practices.pdf, Page 5]\n3. DataHub (by LinkedIn) [Source: data-engineering-best-practices.pdf, Page 5]\n4. Amundsen (by Lyft) [Source: data-engineering-best-practices.pdf, Page 5]\n5. Google [Source: data-security-compliance-guide.pdf, Page 5]\n6. Etsy [Source: data-security-compliance-guide.pdf, Page 5]\n7. PagerDuty [Source: data-security-compliance-guide.pdf, Page 5]\n8. Nexla [Source: data-security-compliance-guide.pdf, Page 2; nexla-platform-overview.pdf, Page 1]\n9. Snowflake [Source: data-security-compliance-guide.pdf, Page 2; nexla-platform-overview.pdf, Page 1]\n10. Databricks [Source: data-security-compliance-guide.pdf, Page 2]\n11. Salesforce [Source: nexla-platform-overview.pdf, Page 1]\n12. HubSpot [Source: nexla-platform-overview.pdf, Page 1]\n13. Workday [Source: nexla-platform-overview.pdf, Page 1]\n14. Palo Alto Networks [Source: nexla-platform-overview.pdf, Page 5]\n15. DoorDash [Source: nexla-platform-overview.pdf, Page 5]\n16. Postmates (now part of Uber) [Source: nexla-platform-overview.pdf, Page 5]\n\nThese companies are mentioned in various contexts related to data engineering, security compliance, and platform capabilities.",
  "sources": [
    { "document": "data-engineering-best-practices.pdf", "page": 5, "relevance_score": -0.3718 },
    { "document": "data-security-compliance-guide.pdf", "page": 5, "relevance_score": -0.397 },
    { "document": "data-security-compliance-guide.pdf", "page": 2, "relevance_score": -0.4686 },
    { "document": "nexla-platform-overview.pdf", "page": 1, "relevance_score": -0.5405 },
    { "document": "data-security-compliance-guide.pdf", "page": 2, "relevance_score": -0.545 },
    { "document": "api-design-best-practices.pdf", "page": 5, "relevance_score": -0.5524 },
    { "document": "nexla-platform-overview.pdf", "page": 5, "relevance_score": -0.5569 }
  ],
  "chunks_used": 7
}

______________________________________________________________________

设计决策与权衡

______________________________________________________________________

Vibe编码：人工智能辅助开发

使用的工具

• Cursor IDE 作为主编辑器，使用Claude（代理模式）进行代码生成和迭代。
• 我保留了一个长时间运行的对话线程，这样AI在构建后续模块时就可以充分了解早期决策的背景。

我如何提示——什么有效，什么无效

什么奏效了：

• *规范优先提示。* 在要求AI生成任何代码之前，我写下了完整的项目结构、每个类名、每个函数签名和确切的返回类型。这种前期的努力得到了回报—— config.py, ingestion.py，以及 retrieval.py 无需进行重大重写即可使用。
• *依赖关系有序生成。* 按顺序请求文件（config→ 摄入→ 检索→ 服务器→ main）意味着每个文件都可以从已经构建的文件中导入。在之前的尝试中，当我尝试一次生成所有内容时，人工智能生成的导入在文件之间不匹配。
• *命名特定的故障模式。* 告诉AI“ChromaDB的 query() 投掷if n_results 为0——警惕“产生了一个精确的 min(top_k, collection.count()) 检查。说“添加错误处理”产生了一个通用的 try/except 它抓住了所有东西，却没有任何有用的东西。

什么不起作用：

• *模糊的提示会产生模糊的代码。* 早些时候，我说“在检索层添加错误处理”。人工智能包裹了整个 generate_answer 方法广泛 except Exception 并返回了一个空的dict。我必须特别指出：“如果LLM API调用失败，请返回原始检索的chunk及其源元数据。”
• *人工智能自信地使用错误的API签名。* FastMCP构造函数需要 instructions= 作为其关键字参数，不是 description=.使用的AI description= 它看起来非常合理——没有语法错误，没有运行时崩溃，它只是默默地什么也没做。我抓住它只是因为我交叉引用了MCP SDK源代码。这是人工智能错误中最危险的一类：运行良好但不符合你想法的代码。
• *多文件状态错误对AI来说是不可见的。* 在添加了强制重新摄取（删除和重新创建ChromaDB集合）后，检索器的集合句柄变得陈旧——它仍然指向旧的、已删除的集合。AI没有标记这一点，因为它独立生成了每个文件。我是在Docker测试崩溃时才发现的 NotFoundError。修复方法是添加一个 _refresh_collection() 回退，但错误本身是人工智能一直错过的跨模块状态问题。

人工智能在哪里发挥了作用，而我在哪里介入

AI在以下方面表现出色：

• *锅炉板和SDK接线。* ChromaDB客户端设置、OpenAI/Anthropic SDK调用、FastMCP工具装饰器和Dockerfile在第一次尝试时都是正确的。这就是人工智能节省时间最多的地方——根据文档连接库。
• *算法建议。* 句子边界感知分块逻辑（用 rfind 为了 . 或 \n\n 在块窗口内）是由AI提出的，比我从头开始写的更清晰。
• *结构脚手架。* 项目布局， pyproject.toml, docker-compose.yml，以及 .gitignore 无需迭代即可正确生成。

我必须重写或更正的地方：

• *接地提示需要三次迭代。* 人工智能的第一个系统提示太宽松了——它让法学硕士从常识中“填补空白”，这违背了RAG的观点。我重写了约束条件，明确地说：只能从提供的上下文中回答，引用每一个声明，如果上下文不足，就说“我不知道”。
• *基于哈希的重复数据消除作用域。* AI的第一个版本计算了每个块的哈希值，这意味着重新摄入相同的PDF将创建具有不同ID的重复块。我将其更改为文件级别的哈希值——每个PDF一个MD5，如果哈希值匹配，则跳过整个文件。
• *Docker环境差异。* AI没有考虑到ChromaDB在新容器中首次运行时下载其嵌入模型（约80MB）的事实。我必须验证这是否有效，并确保容器在初始运行期间具有网络访问权限。

Vibe编码的真正挑战（经验教训）

这些是我反复遇到的模式——不仅在这个项目上，而且在用人工智能构建时：

1. “它可以编译，所以它一定是正确的。” AI生成的代码几乎总是在没有语法错误的情况下运行。这些错误是语义上的——错误的参数名称、过时的引用、处理快乐路径但在边缘情况下中断的逻辑。你必须真的 *跑* 代码与实际输入相对应。Docker测试运行发现了两个在编辑器中看起来不错的bug。

1. 上下文窗口失忆症。 在长时间的交谈中，人工智能逐渐失去了对早期决策的跟踪。我定义了 collection_name 在 config.py但当我开始建造时 server.py，AI有时会硬编码 "documents" 而不是引用 settings.collection_name。每次将谈话重点放在一个文件上会有所帮助，但你必须注意偏差。

1. 无需校准即可获得信心。 人工智能从不说“我不确定这个API。”它将使用 description= 而不是 instructions= 完全有信心。唯一的辩护是阅读实际的库源或文档——这就是工程判断的意思。

1. AI低估了集成的复杂性。 单独来看，每个模块都是正确的。虫子出现在 *边界* --ingester删除一个集合，retriever不知道它；config加载env变量，但Docker入口点传递它们的方式不同。人工智能擅长单文件代码，但在系统级思维方面较弱。

1. 世代相传是真实的。 AI会很乐意添加你没有要求的功能——额外的错误类、冗长的日志包装器、没有人需要的配置选项。我必须积极修剪生成的代码，以保持项目的重点和可读性。更多的代码不是更好的代码。

我对正向部署工程中人工智能工具的看法

对于一个前沿部署的工程角色——你在紧迫的时间线上为有独特需求的客户交付集成——人工智能编码工具确实具有变革性，但不是人们通常描述的方式。

值不是“AI为我写代码”。值是 *常规零件的压缩* 因此，您可以将时间花在真正重要的部分上：了解客户的数据模型，为他们在生产中遇到的边缘情况进行设计，并做出可以捍卫的架构决策。

在这个项目中，人工智能处理了大约70%的原始代码生成。但我大部分时间都花在了另外30%上——接地提示措辞、重复数据删除策略、过时的句柄错误、Docker测试。这30%是工程判断的所在，而这正是人工智能无法为你做的部分。

从这些工具中获得最大收益的工程师是那些已经知道好代码是什么样子的人。如果你无法发现错误的API签名或丢失的状态刷新，人工智能将满怀信心地为你运送这些错误。该工具放大了你对它的任何判断水平。

______________________________________________________________________

许可证

麻省理工学院——见 许可证 了解详情。