AI导哈

文档搜索服务器

一个为AI模型提供实时访问Talos Linux文档的MCP服务器，支持全文搜索、版本过滤和平台特定文档检索。

  • by madeofpendletonwool
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 madeofpendletonwool/talos-mcp

使用说明

Talos Linux 文档 MCP 服务器

一个模型上下文协议（MCP）服务器，为人工智能模型提供实时访问最新Talos Linux文档的功能 Sidero Labs 文档存储库.

概述

这个MCP服务器使AI助手能够搜索和检索最新的Talos Linux文档，包括：

  • 适用于各种平台（AWS、Azure、裸机等）的安装指南
  • 配置和网络文档
  • 安全最佳实践
  • 升级程序
  • 故障排除指南
  • 特定版本的文档（v1.6 - v1.11+）

特点/特性

  • 全文搜索使用Bleve引擎在所有Talos文档中进行搜索
  • 版本过滤在特定的Talos版本中搜索
  • 平台特定文档按云服务提供商或硬件平台筛选
  • 实时更新基于Git与上游仓库的同步
  • 原子索引更新零停机时间文档更新
  • 5种MCP工具针对不同文档查询的专业工具

安装

先决条件

  • Go 1.25.1 或更高版本
  • Git（用于文档同步）

从源代码构建

git clone <repository-url>
cd talos-mcp
go mod download
go build -o talos-mcp

使用方法

运行服务器

根据MCP规范，服务器通过标准输入/输出（stdio）进行通信：

./talos-mcp

通过环境变量进行配置

# Server configuration
export TALOS_MCP_NAME="talos-docs-mcp"
export TALOS_MCP_VERSION="1.0.0"

# Repository settings
export TALOS_MCP_REPO_URL="https://github.com/siderolabs/docs"
export TALOS_MCP_BRANCH="main"

# Search index location
export TALOS_MCP_INDEX_PATH="./data/search_index"

# Webhook secret (if using webhooks)
export TALOS_MCP_WEBHOOK_SECRET="your-secret-here"

# Logging
export TALOS_MCP_LOG_LEVEL="debug"  # Options: debug, info, warn, error

# Run the server
./talos-mcp

与Claude桌面版集成

在您的Claude Desktop配置文件中添加：

macOS（发音为 /ˈmækOS/，可译为“麦奥克斯”或直接保留原英文名，因其已成为一个专有名词）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json Linux（发音类似“林克斯”，但中文里通常直接使用原名）: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "talos-docs": {
      "command": "/path/to/talos-mcp",
      "env": {
        "TALOS_MCP_LOG_LEVEL": "info",
        "TALOS_MCP_INDEX_PATH": "/path/to/index"
      }
    }
  }
}

可用的MCP工具

1. search_talos_docs

在所有 Talos Linux 文档中进行搜索。

参数：

  • query (字符串，必填)：搜索查询
  • version (字符串，可选)：Talos 版本过滤器（例如，“v1.8”，“v1.11”）
  • section （字符串，可选）：部分过滤器（例如，“getting-started”（入门）、“networking”（网络）、“security”（安全））
  • platform (字符串，可选)：平台过滤器（例如，“aws”，“azure”，“bare-metal”）
  • limit （数字，可选）：最大结果数（默认：20）

示例：

{
  "query": "kubernetes upgrade",
  "version": "v1.8",
  "limit": 10
}

2. get_talos_guide

获取特定 Talos 主题的完整指南。

参数：

  • topic （字符串，必填）：指南主题（例如，“快速入门”、“网络配置”、“升级”）
  • version (字符串，可选)：Talos 版本
  • platform （字符串，可选）：特定于平台的变体

示例：

{
  "topic": "quickstart",
  "platform": "aws"
}

3. compare_talos_versions

比较不同Talos版本的文档以识别变更。

参数：

  • topic （字符串，必填）：要比较的主题
  • from_version (字符串，必填)：起始版本
  • to_version （字符串，必填）：目标版本

示例：

{
  "topic": "networking",
  "from_version": "v1.7",
  "to_version": "v1.8"
}

4. get_platform_specific_docs

获取针对特定平台的安装和配置指南。

参数：

  • platform （字符串，必填）：云平台或硬件（例如，“aws”，“azure”，“raspberry-pi”）
  • version (字符串，可选)：Talos 版本

示例：

{
  "platform": "aws",
  "version": "v1.8"
}

5. get_latest_release_notes

获取最新的Talos发布信息及新增功能。

参数： 无

建筑

组件

  1. 文档获取器 （fetcher.go）

    • 克隆/更新 Sidero Labs 文档仓库
    • 解析MDX/MD文件和导航结构
    • 提取元数据（版本、平台、标签）
    • 带有指数退避的后台同步

  2. 搜索引擎 (search.go)

    • Bleve 全文搜索索引
    • 原子索引交换以实现零停机时间更新
    • 内容分类法（版本、部分、平台、标签）
    • 代码片段和上下文提取

  3. MCP 服务器 (server.go）

    • 实现了5种专业文档工具
    • 通过标准输入输出处理MCP协议通信
    • 请求验证和错误处理

  4. 数据模型 (models.go)

    • 带有元数据的文档结构
    • 搜索请求/响应类型
    • 配置模式（或配置架构）

目录结构

talos-mcp/
├── main.go           # Entry point and configuration loading
├── server.go         # MCP server implementation
├── fetcher.go        # Documentation fetching and parsing
├── search.go         # Search engine with Bleve
├── models.go         # Data structures
├── go.mod            # Go module dependencies
├── go.sum            # Dependency checksums
└── data/
    └── search_index/
        ├── active/   # Active search index
        ├── staging/  # Staging index for updates
        └── backup/   # Backup of previous index

数据流

  1. 初始化：

    • 将Talos文档仓库克隆到临时目录
    • 解析 docs.json 导航结构
    • 提取并为所有MDX/MD文档建立索引
    • 使用Bleve构建搜索索引

  2. 查询处理：

    • 通过标准输入输出（stdio）接收MCP工具请求
    • 解析并验证参数
    • 执行带过滤器的搜索
    • 格式化并返回JSON结果

  3. 背景更新：

    • 定期检查Git仓库的更改（间隔5-30分钟）
    • 检测到更改时：拉取最新版本，重新索引文档
    • 原子交换：从预发布阶段进入活跃阶段（零停机时间）
    • 旧索引已移至备份

发展

项目结构

go build ./...              # Build all packages
go test ./...               # Run all tests
go fmt ./...                # Format code
go vet ./...                # Static analysis
go mod tidy                 # Clean dependencies

在开发中运行

# Enable debug logging
export TALOS_MCP_LOG_LEVEL=debug

# Use custom index path
export TALOS_MCP_INDEX_PATH=./dev_index

# Run server
go run .

使用MCP Inspector进行测试

使用 MCP 检查器 测试服务器：

npx @modelcontextprotocol/inspector go run .

配置参考

默认配置

server:
  name: "talos-docs-mcp"
  version: "1.0.0"

repository:
  url: "https://github.com/siderolabs/docs"
  branch: "main"

sync:
  mode: "hybrid"  # polling, webhook, or hybrid
  polling:
    interval: "5m"
    backoff_max: "30m"
  health_check:
    stale_threshold: "1h"

search:
  index_path: "./data/search_index"
  max_results: 20
  snippet_length: 300

cache:
  ttl: "24h"
  max_size: "1GB"

logging:
  level: "info"
  format: "json"

已知的局限性

  1. 版本排序使用简单的字符串比较（而非语义版本控制）
  2. 搜索过滤手动搜索后过滤（对于大型结果集效果不佳）
  3. 没有Webhook处理程序目前仅支持轮询（计划支持Webhook）
  4. 单一存储库仅支持Sidero Labs文档仓库
  5. 无持久缓存每次重启时都会重新索引文档

路线图

  • [ ] 实现GitHub webhook处理器以实现即时更新
  • [ ] 添加语义版本比较
  • [ ] 使用Bleve查询组合优化搜索
  • [ ] 添加持久化文档缓存
  • [ ] 支持多个文档存储库
  • [ ] 实施使用度量和分析
  • [ ] 添加健康检查端点
  • [ ] Kubernetes 部署清单（或配置文件）

故障排除

服务器无法启动

问题: failed to clone repository 解决方案检查网络连接和仓库URL

问题： failed to create search index 解决方案确保索引路径可写： chmod -R 755 ./data

搜索未返回任何结果

问题索引可能为空或已损坏 解决方案删除索引并重新启动：

rm -rf ./data/search_index
./talos-mcp

内存使用率高

问题内存中的大型文档集 解决方案减少 max_results 或者实现分页功能

做出贡献

欢迎投稿！请：

  1. 为仓库创建分支（或“克隆仓库”）
  2. 创建一个特性分支
  3. 为新功能编写测试
  4. 提交拉取请求

许可证

[在此添加您的许可证]

致谢

相关 MCP