🧠 SuiAgentic

SuiAgentic 是一款基于 FastAPI 的文档嵌入和语义检索应用程序，由 Qdrant 矢量数据库提供支持。它支持您将文档（来自 URL 或本地文件）转换为嵌入，高效存储，并使用自然语言查询检索相关内容。它旨在支持 AI 增强型工具，例如 Cursor、Copilot、Claude 以及其他兼容 MCP 的客户端。

💡 为什么选择 SuiAgentic？许多组织需要将内部文档（例如产品需求文档 (PRD)、设计规范、Wiki）中的上下文集成到开发人员和知识工作者使用的工具中。然而，将来自不同来源的文档整合到一个集中式、可搜索的知识库中既复杂又分散。

SuiAgentic 通过提供一个集中式上下文服务器来解决这个问题，该服务器可以提取、分块、嵌入和索引您的内容，并通过简单的 REST API 和 Web 界面访问。它还支持用作 AI 代理的 MCP 服务器。

🚀 主要功能文档嵌入：从 URL 中提取内容（无论是否经过身份验证），将其拆分成块，生成嵌入，然后将其存储在 Qdrant 中。

语义搜索：使用自然语言查询您的知识库并检索相关的块或文档。

Web UI：易于使用的嵌入和搜索 Web 界面。

REST API：可通过 HTTP 端点完全访问，以实现自动化或集成。

MCP 服务器就绪：与 MCP 兼容的客户端（如 Cursor、Copilot、Claude 等）一起使用。

身份验证支持：支持受保护文档的基本身份验证和承载令牌。

⚙️ 快速入门

克隆存储库

git clone https://github.com/AnhQuan2004/mcp_agent.git
cd mcp_agent

设置 Python 环境

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

安装依赖项

pip install -r requirements.txt

创建 .env 文件（或使用提供的 .env.example）

QDRANT_URL=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=documents

启动 Qdrant（向量 DB）

使用 Docker：

docker run -p 6333:6333 qdrant/qdrant

或者使用帮助脚本：

./runqdrant.sh

运行 Agentic 应用程序

uvicorn app.main:app --reload
# or:
python run.py

访问http://localhost:8000

🌐 Web 界面和 API

Web 用户界面：

/ - 家
/embed — 通过 UI 嵌入文档
/retrieve——语义搜索UI

🔍 POST /检索

{
  "query": "What is the architecture of Sui?",
  "top_k": 5,
  "group_by_doc": true
}

🌍 从 URL 嵌入

公共 URL：

只需通过 API 或 UI 提供 URL — 无需身份验证。

🤖 用作 MCP 服务器

要使用 sui 作为 MCP 服务器：

{
  "mcpServers": {
    "suiAgentic": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

文档上传工具

该目录包含将文档批量上传到您的 SuiAgentic Qdrant 数据库的工具。

可用工具

upload_folder.py - 一个从文件夹上传 PDF 文件的简单脚本
upload_documents.py - 一个用于上传 PDF、DOCX 和 TXT 文件的高级脚本，具有更多选项

Related MCP server: RagDocs MCP Server

先决条件

Python 3.8+
SuiAgentic 应用程序已安装并配置
Qdrant 服务器在本地运行或可通过网络访问
安装所需的依赖项（PyPDF2、python-docx）

基本用法

从文件夹上传 PDF 文件

# Upload all PDFs from a folder
python upload_folder.py /path/to/pdf/folder

# Upload with a prefix (useful for categorizing documents)
python upload_folder.py /path/to/pdf/folder --prefix "Research Papers"

高级文档上传

# Upload all supported documents from a folder and subfolders
python upload_documents.py /path/to/documents --recursive

# Add metadata tags to all documents
python upload_documents.py /path/to/documents --tag category=research --tag project=alpha

# Specify collection name (if not using default)
python upload_documents.py /path/to/documents --collection my_collection

# Complete example with all options
python upload_documents.py /path/to/documents --recursive --prefix "Project X" --tag department=marketing --tag status=final

这些工具的作用

在指定文件夹中查找支持的文档
从每个文档中提取文本内容
将文本拆分成可管理的块
为每个块生成 3072 维嵌入
在 Qdrant 中存储块和嵌入
跟踪每个文档的元数据

命令行参数

上传文件夹.py

folder - 包含 PDF 文件的文件夹路径
--prefix - 添加到文档名称的前缀

上传文档.py

folder - 包含文档的文件夹路径
--prefix - 添加到文档名称的前缀
--recursive - 在子文件夹中递归搜索文件
--collection - 要使用的 Qdrant 集合的名称
--tag - 向文档添加元数据标签（可多次使用： --tag key=value ）

示例

按项目组织文档

python upload_documents.py /path/to/projects/project1 --recursive --prefix "Project 1" --tag project=alpha
python upload_documents.py /path/to/projects/project2 --recursive --prefix "Project 2" --tag project=beta

对文档进行分类

python upload_documents.py /path/to/contracts --prefix "Legal" --tag department=legal --tag confidential=true
python upload_documents.py /path/to/manuals --prefix "Technical" --tag department=engineering

故障排除

如果遇到大型文档的内存错误，请尝试将其拆分为较小的文件
对于大量文档，请考虑以较小的批次进行处理
检查日志输出以查找处理过程中的任何错误

🪪 许可证

根据 Apache License 2.0 授权。

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

SuiAgentic