SSMCP (Antonsokolskyy)

SSMCP-超简单MCP服务器

模型上下文协议（MCP）服务器，提供具有内容提取的网络搜索。

为什么要使用SSMCP？

许多人工智能模型，特别是本地模型或某些基于云的模型，没有内置的网页浏览功能。SSMCP通过提供一个简单的自托管解决方案来弥合这一差距，该解决方案使您的AI助手能够：

• 搜索和阅读网络：让你的AI搜索当前信息、阅读文章、文档或任何网络内容
• 提取清洁内容：自动将杂乱的网页转换为AI模型可以轻松理解的干净Markdown格式
• 访问YouTube成绩单：从带有时间戳的视频中提取字幕进行分析或总结
• AI驱动的总结：可选的LLM摘要仅根据您的搜索查询从网页中提取相关信息
• 注重隐私：自托管解决方案-您的搜索和浏览停留在您的基础设施上
• 适用于任何型号：与支持MCP的本地模型（如Qwen、Llama）和云API（DeepSeek、Claude、GPT）兼容

示例用例：

• 研究某一主题的最新消息或发展
• 阅读并总结技术文档
• 分析当前市场趋势或产品评论
• 从YouTube教程或演示文稿中提取信息
• 获取模型训练数据中没有的最新答案
• 获取简洁、与查询相关的网络内容摘要（启用LLM摘要）

特性

• 网络搜索：搜索网络并获取Markdown中提取内容的结果
• Web提取：从任何URL中提取内容作为干净的Markdown
• YouTube字幕：从YouTube视频中提取字幕和时间戳
• LLM总结 （可选）：使用LLM按与查询的相关性对搜索结果进行汇总和筛选
• 简单API：易于使用的界面设计用于兼容小型本地模型（如Qwen3 30b）和缺乏web功能的云模型（如DeepSeek 3.2）
• 容器支持：使用Docker Compose进行完全容器化部署

快速开始

先决条件

• 码头工人
• Docker Compose

1.克隆此存储库

git clone https://github.com/antonsokolskyy/SSMCP.git

2.创建.env文件

cd SSMCP/
cp .env.example .env

3.设置SearXNG

启动和停止 searxng 要生成的容器 settings.yml:

docker compose up searxng

等到你看到：

"/etc/searxng/settings.yml" does not exist, creating from template...

然后按下 Ctrl+C 阻止它。

编辑 deploy/docker/searxng_data/settings.yml 并添加 json 到 formats 列表：

# remove format to deny access, use lower case.
# formats: [html, csv, json, rss]
formats:
  - html
  - json

4.构建SSMCP映像

docker compose build

5.运行全栈

docker compose up -d

YouTube Cookie（可选）

要访问年龄限制或私人YouTube视频，并减少点击验证码或IP阻止的机会，您可以从浏览器提供Cookie。

注： cookie文件必须采用Netscape cookie格式。

Generating cookies.txt

选项1：使用浏览器扩展

为您的浏览器安装一个扩展程序（如“本地获取cookies.txt”），并以Netscape格式导出youtube.com的Cookie。

选项2：使用yt-dlp二进制文件

yt-dlp --cookies-from-browser chrome --cookies cookies.txt https://www.youtube.com/watch?v=VIDEO_ID

替换 chrome 使用您的浏览器(firefox, edge, safari等等）。这将自动以Netscape格式导出。

Using cookies.txt

放置生成的 cookies.txt 文件位于：

deploy/docker/ssmcp/cookies.txt

安全警告： Cookie文件包含身份验证令牌和敏感数据。设置适当的文件权限以防止未经授权的访问：

chmod 600 deploy/docker/ssmcp/cookies.txt

Docker容器会自动检测并使用该文件。

MCP网址

服务器使用流式HTTP传输。连接到MCP服务器：

http://{HOST}:{PORT}/mcp

例子：

http://localhost:8000/mcp

与MCP客户端一起使用

LM 工作室

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

Web用户界面

SSMCP包括一个可选的Web UI，用于监视请求和响应。这对于调试和检查模型如何使用工具特别有用。

Enabling the Web UI

1. 配置Redis：打开你的 .env 归档并取消注释 REDIS_URL 线路：

REDIS_URL=redis://redis:6379

1. 启用服务：打开 docker-compose.yml （以及 docker-compose.dev.yml 如果使用开发模式）并取消注释 redis 和 ssmcp-ui 服务块。

1. 重启服务:

make build

1. 访问监视器：打开 http://localhost:8081 在您的浏览器中。

工具

网络搜索

执行网络搜索并返回包含提取内容的相关结果。

参数：

• query （str）：搜索查询或关键字以查找相关网络内容

退货：

• 结果列表，每个结果包含：

- url （str）：网页URL - content （str）：Markdown格式的页面内容

web_fetch

从指定的URL获取内容并将其转换为Markdown。

参数：

• url （str）：从中获取内容的URL

退货：

• 包含Markdown格式页面内容的字符串

youtube_get_字幕

从YouTube视频中获取字幕/说明，并返回文本内容。

参数：

• url （str）：用于获取字幕的YouTube视频URL

退货：

• 包含带时间戳的字幕的字符串，格式为：\[HH:MM:SS\]文本

搜索工作原理

SSMCP使用管道从网络搜索中提供干净的内容：

1.搜索（SearXNG）

• 查询被发送到本地 瑟克斯NG 例子
• SearXNG汇总了来自多个搜索引擎的结果
• 返回包含标题和代码段的URL列表

2.内容提取（Crawl4AI）

• 每个URL都是使用无头Chromium浏览器获取的
• 页面完全呈现（JavaScript执行，动态内容加载）
• 提取原始内容
• 所有URL都会同时处理

3.内容过滤

两级过滤提取清洁主要内容：

1. CSS选择器筛选器 -尝试选择器(article, main等）以找到主要内容区域
2. 残留垃圾过滤器 -删除UI工件（工具提示、重复文本）

如果任何过滤器产生输出，则过滤后的HTML将通过Crawl4AI重新处理，以便在markdown转换之前获得更清晰的输出。

4.Markdown转换

• 将过滤后的HTML转换为干净的Markdown
• 删除图像和外部链接

5.可选：LLM摘要

启用后，SSMCP使用LLM来汇总搜索结果，然后将其返回给您的AI模型。这减少了上下文窗口中的令牌计数——搜索结果可能是40k-60k个令牌，但摘要大大减少了这一点。

注： 默认情况下禁用LLM摘要。如果需要，可以通过环境变量启用它（请参阅 .env.example).

发展

所有开发任务都在Docker容器内执行。除了Docker和Docker Compose之外，不需要在主机上安装任何东西。

可用的生成命令

跑 make help 查看所有可用命令：

Development Workflow

1. 启用开发模式：\

打开 .env 并取消注释该行

   COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml

1. 启动服务：

   make build

1. 打开容器中的外壳：

   make shell

在shell中，您可以运行任何命令：

   uv run python -m ssmcp.server
   uv run pytest -v

1. 在主机上编辑代码 -更改会通过卷装载自动反映在容器中

1. 运行测试：

   make test

1. 检查代码质量（lint+类型检查）：

   make check

1. 如果需要，请重新启动或重建：

   make restart
   make rebuild

1. 停止服务：

   make down

配置

所有配置都通过环境变量进行管理。看 .env.example 有关可用选项

OpenWebUI OAuth身份验证

SSMCP支持OAuth身份验证，可与OpenWebUI和任何符合OIDC的身份提供程序一起使用。

OpenWebUI OAuth的工作原理

当您选择 OAuth 在MCP服务器的OpenWebUI中：

• OpenWebUI将系统用户的OAuth访问令牌转发到 Authorization: Bearer 头球
• 令牌是一个JWT，其中包含来自身份提供者的用户信息
• SSMCP验证令牌并从中提取用户标识符 sub 声称

Enabling OAuth

要启用OAuth身份验证，请在您的 .env 文件：

# Enable OAuth authentication
OAUTH_ENABLED=true

# JWKS endpoint URL for your identity provider's public keys
# Examples:
#   Authentik: https://authentik.example.com/application/o/my-app/jwks
OAUTH_JWKS_URL=https://your-idp.example.com/path/to/jwks

# Issuer URL for token issuer verification
# Must match the 'iss' claim in JWT tokens
# Examples
#   Authentik: https://authentik.example.com/application/o/my-app
OAUTH_ISSUER=https://your-idp.example.com/application/o/my-app

# Open WebUI client ID for token audience verification
OAUTH_CLIENT_ID=your-openwebui-client-id

Token Validation

启用OAuth后，SSMCP会验证：

1. JWT签名：使用来自JWKS端点的身份提供程序的公钥验证令牌签名
2. 发行人：验证 iss 索赔匹配 OAUTH_ISSUER
3. 过期：验证 exp claims-拒绝过期的令牌
4. 观众：验证 aud 索赔匹配 OAUTH_CLIENT_ID
5. 主题：需要 sub 声明（包含用户标识符）

OpenWebUI Configuration

在OpenWebUI中，使用以下配置MCP服务器：

• 类型：MCP流式HTTP
• 统一资源定位符：您的SSMCP服务器URL（例如。， http://ssmcp:8000/mcp)
• 认证：OAuth
• 系统将自动转发用户的OAuth令牌

Supported Identity Providers

SSMCP与任何符合OIDC标准的身份提供者合作，这些提供者：

• 为公钥分发提供JWKS端点
• 使用RS256签名发出JWT访问令牌
• 包括标准索赔(sub, aud, exp, iss)

许可证

Apache许可证2.0-请参阅 许可证 文件以获取详细信息。