MCP Fess

mcp-fess

用于Fess搜索引擎的MCP（模型上下文协议）桥接服务器，使大型语言模型（LLM）能够通过结构化工具和资源查询和检索特定于领域的信息。

特性

• MCP协议支持：实现MCP规范版本2025-03-26（默认）和2024-11-05（--cody模式）
• 完全Fess API集成：搜索、建议、流行词、标签和健康检查端点
• 资源管理：将Fess文档作为MCP资源公开，并获取内容
• 基于标签的过滤：灵活的基于标签的搜索，具有可配置的描述和示例
• 标签发现：通过智能缓存从Fess自动发现标签
• 多个传输：stdio（默认）和HTTP传输模式
• 内容提取：获取HTML和PDF文档并将其转换为纯文本
• 安全：可配置的身份验证、主机分配列表和专用网络保护
• 日志记录：全面的日志记录，支持调试模式

安装

快速安装（推荐）

安装MCP Fess最简单的方法是使用自动安装程序：

git clone https://github.com/Buttje/mcp-fess.git
cd mcp-fess
python3 install.py

这将：

• 检测您的操作系统（Windows 10/11、Linux Ubuntu/Red Hat/Fedora）
• 创建虚拟环境(./venv)
• 安装所有必需的依赖项
• 创建特定于操作系统的启动器脚本(start-mcp-fess.sh 或 start-mcp-fess.bat)
• 在以下位置生成初始配置文件 ~/.mcp-feiss/config.json

安装后，您可以直接运行服务器：

在Linux/macOS上：

./start-mcp-fess.sh

在Windows上：

start-mcp-fess.bat

安装程序选项

# Custom virtual environment location
python3 install.py --venv-dir /path/to/venv

# Custom configuration directory
python3 install.py --config-dir /path/to/config

# Skip creating initial configuration
python3 install.py --no-config

# Show help
python3 install.py --help

手动安装（来源）

如果您更喜欢手动安装：

git clone https://github.com/Buttje/mcp-fess.git
cd mcp-fess
pip install -e .

需求

• Python 3.10或更高版本
• 正在运行的Fess服务器实例

配置

在以下位置创建配置文件 ~/.mcp-fess/config.json.

最小配置

最简单的配置只需要Fess服务器URL：

{
  "fessBaseUrl": "http://localhost:8080"
}

这将为所有可选字段使用默认值，包括默认域 id="default" 和 name="Default Domain".

完整配置示例

对于生产使用，您应该提供明确的域信息并配置其他设置：

{
  "fessBaseUrl": "http://localhost:8080",
  "domain": {
    "id": "my_domain",
    "name": "My Knowledge Domain",
    "description": "Description of the knowledge domain"
  },
  "labels": {
    "all": {
      "title": "All documents",
      "description": "Search across the whole Fess index without label filtering.",
      "examples": ["company policy", "architecture decision record"]
    },
    "hr": {
      "title": "HR policies",
      "description": "Employee handbook, benefits, leave, HR forms.",
      "examples": ["vacation policy", "parental leave"]
    },
    "engineering": {
      "title": "Engineering documentation",
      "description": "Technical documentation, API references, architecture guides.",
      "examples": ["API documentation", "deployment guide"]
    }
  },
  "defaultLabel": "all",
  "strictLabels": true,
  "httpTransport": {
    "bindAddress": "127.0.0.1",
    "port": 3000,
    "path": "/mcp",
    "enableSse": true
  },
  "timeouts": {
    "fessRequestTimeoutMs": 30000,
    "longRunningThresholdMs": 2000
  },
  "limits": {
    "maxPageSize": 100,
    "maxChunkBytes": 1048576,
    "maxInFlightRequests": 32
  },
  "logging": {
    "level": "info",
    "retainDays": 7
  },
  "security": {
    "httpAuthToken": null,
    "allowNonLocalhostBind": false
  },
  "contentFetch": {
    "enabled": true,
    "maxBytes": 5242880,
    "timeoutMs": 20000,
    "allowedSchemes": ["http", "https"],
    "allowPrivateNetworkTargets": false,
    "allowedHostAllowlist": null,
    "userAgent": "MCP-Fess/1.0",
    "enablePdf": false
  }
}

配置字段

• fessBaseUrl （必填）：Fess服务器的基本URL
• 领域 （可选）：具有id、名称和可选描述的域配置

- 默认为 {"id": "default", "name": "Default Domain"} 如果未指定 - 建议提供有意义的值，以便更好地识别工具

• 标签 （可选）：带有描述和示例的标签定义

- 每个标签都有一个 title, description，以及 examples 数组 - 这 "all" 标签始终可用（即使没有明确配置），意味着“没有标签过滤” - 标签描述存储在MCP配置中，而不是Fess中

• 默认标签 （可选，默认：“all”）：在搜索中未指定标签时使用的默认标签
• 严格标签 （可选，默认值：true）：

- true：只允许配置中定义的标签或Fess中存在的标签 - false：允许任何标签值（警告未定义的标签）

• httpTransport：HTTP传输设置（用于HTTP模式）
• 超时：请求超时配置
• 限制：请求和答复的资源限制

- maxPageSize：每页的最大搜索结果数（默认值为100） - maxChunkBytes：read_doc_content和fetch_content_chunk返回的最大字节数（默认1048576=1 MiB） - maxInFlightRequests：最大并发请求数（默认值32）

• 日志记录：日志记录级别和保留设置
• 安全：身份验证和网络安全设置
• contentFetch：文档内容获取配置

向后兼容

为了与旧配置向后兼容， domain.labelFilter 仍受支持，但已弃用：

{
  "domain": {
    "id": "my_domain",
    "name": "My Knowledge Domain",
    "labelFilter": "my_label"
  }
}

当 domain.labelFilter 存在并且 defaultLabel 如果未明确设置，服务器将使用 labelFilter 作为默认标签，并记录弃用警告。我们建议迁移到新的配置格式：

{
  "domain": {
    "id": "my_domain",
    "name": "My Knowledge Domain"
  },
  "defaultLabel": "my_label",
  "labels": {
    "my_label": {
      "title": "My Label",
      "description": "Documents with my_label",
      "examples": []
    }
  }
}

用法

基本用法（标准传输）

mcp-fess

使用FastMCP命令行界面

您还可以使用 fastmcp CLI工具：

fastmcp run src/mcp_fess/app.py

或者直接使用该软件包：

python -m mcp_fess

使用调试日志记录

mcp-fess --debug

调试日志将写入 ~/.mcp-fess/log/_server.log 带有经过时间前缀。

HTTP传输

mcp-fess --transport http

使用可选 --port 从配置中覆盖端口的标志（默认值：3000）：

mcp-fess --transport http --port 8080

科迪模式（MCP 2024-11-05）

mcp-fess --cody

配置

在以下位置创建配置文件 ~/.mcp-fess/config.json.

代理工作流

MCP Fess为代理提供了一个结构化的工作流程，以有效地从Fess中搜索和检索信息：

高效的搜索策略

1. （可选）发现标签：呼叫 list_labels 如果需要限制搜索空间，请选择标签范围
2. 搜索文档：呼叫 search 获取相关点击并收集 doc_ids
3. 获取内容：呼叫 fetch_content_chunk （首选）或 fetch_content_by_id 从索引中读取提取的UTF-8文本证据
4. 精炼：使用证据来细化查询；可选使用 suggest 和 popular_words 扩展/旋转

内容检索

• 搜索结果 仅包含简短的摘要/代码段字段
• 完整文档文本 从Fess索引检索（不是从源URL检索）
• 文本源优先级: content 领域→ body 领域→ digest 领域
• 分块：对于超过最大块大小的文档，请使用 fetch_content_chunk 迭代内容：

- 从...开始 offset=0 - 如果 hasMore=true，set offset = offset + returned_length 然后再打来 - 重复直到 hasMore=false

性能提示

• 使用 include_fields 搜索中的参数，用于将有效载荷限制在所需字段
• 对大型文档使用分块，而不是一次获取整个内容
• 利用标签来确定搜索范围并减少结果集

代码段引擎

代码片段引擎将源文档转换为适合Fess索引的小型Markdown文件。

新配置密钥

路径映射（Docker/容器设置）

当Fess在Docker中运行时，存储在索引中的文档路径指向 *容器* 文件系统（例如。 /data/fess/my-doc.pdf).这 fess_get_original_doc 工具以两种方式将这些转换为主机路径：

1. 明确的 pathMappings --将条目添加到您的 config.json:

{
  "pathMappings": [
    { "container": "/data/fess", "host": "/host/path/to/fess/data" }
  ]
}

每个条目都将容器路径前缀替换为匹配的主机路径前缀。第一个匹配的条目获胜。

1. 通过自动检测 fessComposePath --如果 fessComposePath 指向您的合成文件，服务器读取其卷映射 fessDataMount 自动。没有明确 pathMappings 在这种情况下，数据装载需要输入。

明确的 pathMappings 优先于基于组合的自动检测。

CLI使用情况

mcp-fess-snippets --input /path/to/docs --output-folder MY_DOCS [--include '**/*.pdf'] [--exclude '**/*.tmp'] [--verbose]

MCP工具

• fess_get_original_doc --按ID检索索引文档的原始文件系统路径。
• fess_generate_snippets --扫描目录，将文档转换为Markdown代码段，并将其写入配置的Fess数据挂载下。

MCP工具

服务器公开以下工具（前缀为 fess_):

1.搜索工具

在Fess中搜索文档。 当你需要真实的内部信息时，使用这个工具；不要猜测，先搜索。

参数：

• query （必填）：搜索词
• label （可选）：标签值以确定搜索范围

- 使用 "all" （默认）在不进行标签筛选的情况下搜索整个索引 - 使用特定的标签值（例如。， "hr", "engineering")在该标签内搜索 - 呼叫 list_labels 查看可用标签及其说明

• pageSize （可选）：结果数量（默认20，最大100）
• start （可选）：起始索引（默认值0）
• sort （可选）：排序顺序
• lang （可选）：搜索语言
• includeFields （可选）：要包含在结果中的字段

标签行为：

• 当 label="all"：未应用标签筛选器（搜索整个Fess索引）
• 当 label=：适用 fields.label=[] 过滤到Fess查询
• 当省略标签时：使用配置的 defaultLabel

2.列表标签工具

列出可用的Fess标签以及每个标签包含的内容。 如果不确定使用哪个标签，请拨打此电话。

返回标签目录，其中包含：

• 标签值和名称
• 说明和使用示例（来自MCP配置）
• 可用性状态（仅存在于Fess或配置中）
• 默认标签设置
• 严格模式状态

3.建议工具

根据索引词汇表获取查询建议。在审查证据后使用，以生成固定的查询扩展（同义词、前缀、近义词）。

参数：

• prefix （必填）：搜索前缀
• num （可选）：建议数（默认10）
• fields （可选）：要搜索的字段
• lang （可选）：语言

4.流行词工具

从索引中获取流行词/术语。用于发现枢轴、过滤器和后续查询公式的主要词汇。

参数：

• seed （可选）：随机种子
• field （可选）：字段名称

5.健康工具

检查Fess服务器运行状况。

6.作业进度工具

查询长时间运行的操作的状态。

参数：

• jobId （必填）：作业标识符

7.获取内容块工具

从Fess索引中获取文档的提取UTF-8文本窗口（不获取源URL）。

使用此后 search 当你需要实质性证据（章节/整份文件）时。

文本来源： 仅索引字段（优先级： content → body → digest).未获取源URL。

参数：

• doc_id （必填）：从搜索结果中获得的文档ID
• offset （可选）：字符偏移到文档中（默认为0）
• length （可选）：要返回的字符数（默认maxChunkBytes）

退货： JSON格式：

• content：请求的文本块
• hasMore：布尔值，指示此块之外是否存在更多内容
• offset：此块的起始位置
• length：返回内容的实际长度
• totalLength：文档总长度（字符）

例子：

{
  "content": "Document content...",
  "hasMore": true,
  "offset": 0,
  "length": 1048576,
  "totalLength": 2500000
}

要检索下一个块，请使用 offset: 1048576 与相同 length.

8.通过ID工具获取内容

在一次调用中从Fess索引中提取文档的UTF-8文本（不提取源URL）。

当文档预计符合服务器的最大块限制时，或者当您希望在不管理偏移的情况下快速阅读时使用。如果文档超过限制，内容将被截断；使用 fetch_content_chunk 用于完全遍历。

文本来源： 仅索引字段（优先级： content → body → digest).未获取源URL。

参数：

• doc_id （必填）：从搜索结果中获得的文档ID

退货： JSON格式：

• content：文档内容（最大块大小）
• totalLength：文档总长度（字符）
• truncated：布尔值，指示内容是否因大小限制而被截断

MCP资源

文档和标签作为具有URI的资源公开：

• fess:///doc/ -文档元数据。使用 doc/{doc_id}/content 或者使用内容提取工具来检索提取的文本。
• fess:///doc//content -文档提取文本（仅索引）。返回服务器的最大块限制。对于较长的文档，请使用 fetch_content_chunk 迭代完整的提取文本。
• fess:///labels -可用标签目录及说明。

代理商的最佳实践

当将MCP-Fess与LLM试剂一起使用时：

1. 标签发现：呼叫 list_labels 在会话开始时或切换域以了解可用搜索空间时
2. 更喜欢特定标签：使用特定标签（例如。， "hr", "engineering")完毕 "all" 当用户意图明确时，可获得更集中的结果
3. 先搜索：始终搜索事实信息，而不是猜测或依赖常识
4. 逐步细化：从更广泛的搜索开始(label="all")并根据初步结果使用特定标签进行细化
5. 大型文档：使用 fetch_content_chunk 当文档超过maxChunkBytes（默认1 MiB）时检索其他内容的工具

标签配置指南

MCP Fess中的标签作为搜索空间，帮助代理找到正确的信息：

标签说明

• 存储在MCP配置中，不在Fess中（Fess标签API仅提供标签值和名称）
• 包括有意义的描述来指导代理行为
• 提供每个标签的典型查询示例

标签发现

• 标签通过以下方式从Fess自动发现 /api/v1/labels API
• 缓存5分钟以减少Fess的负载
• 配置定义的标签与实时Fess标签合并

严格模式

• 严格=真 （默认）：仅允许在配置中定义或存在于Fess中的标签
• 严格=假：允许在开发过程中或标签结构动态时使用任何标签值

配置示例

{
  "labels": {
    "all": {
      "title": "All documents",
      "description": "Search across the whole Fess index without label filtering.",
      "examples": ["company policy", "org chart"]
    },
    "hr": {
      "title": "HR policies",
      "description": "Employee handbook, benefits, leave policies, HR forms, and onboarding guides.",
      "examples": ["vacation policy", "parental leave", "401k enrollment"]
    },
    "engineering": {
      "title": "Engineering documentation",
      "description": "Technical docs, API references, architecture guides, deployment procedures.",
      "examples": ["API authentication", "deployment checklist", "system architecture"]
    },
    "product": {
      "title": "Product documentation",
      "description": "Product specs, roadmaps, feature docs, user guides.",
      "examples": ["feature requirements", "product roadmap Q1"]
    }
  },
  "defaultLabel": "all",
  "strictLabels": true
}

发展

看 贡献.md 用于开发设置和指南。

快速开始

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src tests

# Run type checking
mypy src

# Format code
ruff format src tests

建筑

服务器由以下部分组成：

• 配置模块 (config.py)：加载并验证配置
• Fess客户端 (fess_client.py)：Fess REST API的HTTP客户端
• 服务器 (server.py)：使用工具和资源实现MCP服务器
• 日志记录 (logging_utils.py)：具有运行时间支持的日志记录实用程序

安全注意事项

• 默认绑定仅为环回（127.0.0.1）
• 通过承载令牌进行HTTP身份验证（可选）
• 专用网络目标阻止（可配置）
• 主机分配内容获取
• 内容获取的方案限制

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

贡献

欢迎投稿！请参阅 贡献.md 作为指导方针。

参考文献

• Fess API文件
• 模型上下文协议