websharp

WebSharp MCP HTTP 服务

WebSharp 是一个使用 C#（.NET 9）编写的模型上下文协议（MCP）服务，通过可流式传输的 HTTP 传输方式提供网页搜索和可读网页提取工具。它结合了 SearXNG 元搜索实例与 SmartReader 内容提取库，并附带 Docker 相关资源，让你只需一条命令即可在本地运行所有组件。

亮点

• 由 ASP.NET Core 通过 ModelContextProtocol.AspNetCore 提供的可流式传输 HTTP MCP 端点。
• 由 SearXNG 支持的元搜索工具，可同时返回易读摘要和结构化 JSON 元数据。
• 由 SmartReader 提供支持的网页阅读工具，可读取单个 URL 或批量读取，适合用于信息依据和事实核查工作流。
• 以容器为先的开发体验，提供 Docker Compose 和适用于 inspector 的 .mcp.json 配置文件。

可用的 MCP 工具

web_search

参数	类型	默认值	说明
query	string	必填	提交给已配置搜索后端的自由格式搜索字符串（默认为 SearXNG）。
limit	integer	10	文本摘要中显示的最大结果数。设为 0 或负数时，将省略此参数，由后端决定结果数量。
categories	string	"general"	转发给后端的逗号分隔类别（对于 SearXNG，示例包括 general,it,science）。
language	string	"en"	转发给后端的语言标记。使用默认 SearXNG 实例时，请参阅其语言列表。

响应

• 显示热门结果、相关建议及任何无响应引擎的文本摘要。
• structuredContent 包含一个 JSON 对象，其中有：
  • query：回显执行过的查询字符串。
  • items：结果对象数组（title、url、content、engine/engines、category、positions、parsed_url）。
  • suggestions：后端返回的相关查询（SearXNG 会在有相关查询时显示）。
  • unresponsive_engines：超时或失败的引擎列表，以及可选的消息。
  • error：搜索无法完成时出现。

web_page_read

参数	类型	默认值	说明
urls	array	必填	一个或多个要获取并解析的绝对 HTTP/HTTPS URL。

响应

• 提供单个 URL 时，返回文章标题、摘要、可读文本预览（约 800 个字符）以及页脚元数据（源 URL、检测到的语言）。
• 提供多个 URL 时，摘要会包含总体成功／失败数量、每个页面的详细信息（标题、URL、全文、语言）以及失败时的错误消息。请求会并发运行，并遵循 MCP 取消令牌。
• 不会填充 structuredContent；所有数据都在文本块中返回。

使用 Docker Compose 运行所有组件

1. 安装 Docker Desktop（或其他兼容 OCI 的运行时）并确保其正在运行。
2. 在仓库根目录启动 SearXNG 依赖项和 MCP 服务：
   docker compose -f docker-compose.yaml --project-name websharp up -d（首次运行或 Dockerfile 更改时，请添加 --build）。
3. 等待 websharp-mcp 容器报告 Now listening on: http://0.0.0.0:8080。
4. 现在可以通过 http://localhost:8081 访问 MCP 服务（映射自容器端口 8080）。SearXNG 可通过 http://localhost:8080/ 访问，供检查使用。

手动构建 Docker 镜像

在仓库根目录中运行服务器镜像构建命令，无需 Docker Compose：

docker build -f .\src\WebSharp.Mcp.Http\Dockerfile -t jessegador/websharp-mcp:v0.99.0-rc2 --no-cache src

将 -t 更新为你计划发布的镜像仓库和标签。

使用 MCP Inspector 连接

1. 启动（或保持运行）上述 compose 堆栈。
2. 使用随附的客户端配置启动 Inspector：
   npx -y @modelcontextprotocol/inspector --config .\.mcp.json --server websharp-mcp
3. 在浏览器中打开 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>，将打印出的令牌复制到 Inspector UI 中。
4. 在 Inspector UI 中选择 websharp-mcp 服务，探索可用工具并立即尝试调用。

从源代码运行

• 安装 .NET 9 SDK。
• 确保可以访问 SearXNG 端点。最简单的方法是继续使用 Docker Compose 服务，并在启动应用前将 Searxng__BaseUrl 导出为 http://localhost:8080。
• 启动服务：
  dotnet run --project src/WebSharp.Mcp.Http/WebSharp.Mcp.Http.csproj --urls http://localhost:8081
• MCP 端点监听 /。在 DEBUG 构建中，可以访问 /__routes 检查已配置的 ASP.NET 端点。

配置

环境变量	默认值	描述
ASPNETCORE_URLS	http://0.0.0.0:8080（Docker）	HTTP 服务的监听地址。可覆盖此值以更改对外开放的 MCP 端口。
Searxng__BaseUrl	http://searxng:8080	SearXNG 实例的基础 URL。如果未运行随附的 Docker 服务，则必须设置此项。必须为绝对 URI。
Cors__AllowAnyOrigin	true	允许所有来源。若要通过 Cors__AllowedOrigins__0=<origin> 这类键限制调用方，请将其设为 false。
Cors__AllowAnyHeader	true	允许所有请求标头。
Cors__AllowAnyMethod	true	允许所有 HTTP 方法。
Cors__AllowCredentials	false	设为 true 时，将接受凭据，并且必须明确列出允许的来源。
Cors__AllowedOrigins__{n}	(空)	当 AllowAnyOrigin 为 false 时，可选的来源允许列表项。
Cors__AllowedHeaders__{n}	(空)	可选的标头允许列表。
Cors__AllowedMethods__{n}	(空)	可选的方法允许列表。

所有配置值也可以通过 appsettings.json/appsettings.Development.json 提供。Docker Compose 定义会挂载正确的默认值，方便本地试用。

使用其他 SearXNG 实例

• 将 Searxng__BaseUrl 指向托管的 SearXNG 部署（例如 https://searxng.example.com）。
• 确保目标端点提供 SearXNG 搜索 API，并允许所请求的类别和语言。
• 在发布到 MCP 注册表之前，可考虑调整随附的 searxng/settings.yml，配置启用的引擎、安全搜索或速率限制。

安全说明

• HTTP 传输不包含身份验证。若要在 localhost 之外开放访问，请通过反向代理、隧道或 VPN 运行。
• CORS 默认采用宽松设置，便于调试。在共享环境中部署前，请收紧这些设置。
• 服务遵循 MCP 取消令牌，并为页面抓取设置较短的 HTTP 超时时间，以避免客户端会话挂起。

注册表元数据

• 名称：websharp-mcp
• 传输方式：streamable-http
• 端点：/
• 查看 .mcp.json，其中包含可直接使用的 Inspector 配置。

许可证

本项目采用 MIT 许可证（参见 LICENSE）。