MCP服务器系统
用于与Systembolaget的API交互的模型上下文协议（MCP）服务器。此服务器提供用于搜索产品、检索产品详细信息、查找商店和获取商店信息的工具。
特性
可用工具
- 系统博客_搜索_产品 -在Systembolaget的目录中搜索产品
- 按类别、价格范围、酒精含量、国家/地区筛选 - 支持分页 - 返回详细的产品信息，包括口味特征
- systembolage_get_product -获取特定产品的详细信息
- 全面的产品详情 - 口味特征和食物搭配 - 服务建议
- 系统博客_搜索_存储 -搜索Systembolaget商店
- 按名称或城市查找商店 - 显示店铺位置、营业时间和坐标 - 分页支持
安装
先决条件
- Python 3.10或更高版本
- 紫外线 -快速Python包安装程序
注： 不需要API密钥！服务器自动从Systembolaget的网站中提取API密钥。
紫外线设置（推荐）
- 如果您还没有安装uv：
curl -LsSf https://astral.sh/uv/install.sh | sh- 克隆此存储库：
git clone https://github.com/fldc/systembolaget-mcp.git
cd systembolaget-mcp- 安装依赖项：
uv sync或者安装开发依赖项：
uv sync --all-extras- （可选）配置自定义API密钥：
export SYSTEMBOLAGET_API_KEY="your-api-key-here"或者创建一个 .env 文件：
SYSTEMBOLAGET_API_KEY=your-api-key-hereAPI密钥是可选的。 如果没有提供，服务器将自动从Systembolaget的网站中提取它。
替代方案：使用pip进行设置
如果你更喜欢使用pip：
pip install -e .
# Or with dev dependencies:
pip install -e ".[dev]"用法
运行服务器
使用克劳德桌面
将此配置添加到您的Claude Desktop配置文件中：
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json
使用紫外线（推荐）：
{
"mcpServers": {
"systembolaget": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/systembolaget-mcp",
"run",
"systembolaget_mcp.py"
]
}
}
}直接使用Python：
{
"mcpServers": {
"systembolaget": {
"command": "python",
"args": ["/absolute/path/to/systembolaget-mcp/systembolaget_mcp.py"]
}
}
}注： 这 env 部分与 SYSTEMBOLAGET_API_KEY 是可选的。如果没有提供，服务器将自动提取API密钥。
独立测试
重要提示： MCP服务器通过JSON-RPC协议进行通信。您不能直接将纯文本发送到服务器。
快速测试（推荐）：
# Test the server functions directly
uv run test_server.py以MCP服务器运行：
# This starts the JSON-RPC server (waits for JSON-RPC messages via stdin)
uv run systembolaget_mcp.py有关详细的测试说明，请参阅 测试.md.
查询示例
通过Claude Desktop连接后，您可以提出以下问题：
- “搜索50瑞典克朗以下的瑞典啤酒”
- “寻找酒精含量在12-14%之间的意大利葡萄酒”
- “给我看看斯德哥尔摩的商店”
- “获取产品编号12345的详细信息”
- “乌普萨拉这家店的营业时间是什么时候？”
工具参考
系统博客_搜索_产品
搜索具有各种过滤器的产品。
参数：
query（可选）：产品名称搜索查询category（可选）：按类别筛选（例如，“Öl”、“Vin”、“Sprit”）min_price（可选）：最低价格（瑞典克朗）max_price（可选）：最高价格（瑞典克朗）min_alcohol（可选）：最低酒精百分比（0-100）max_alcohol（可选）：最大酒精百分比（0-100）country（可选）：按原产国筛选limit（可选）：结果数量（默认值：20，最大值：100）offset（可选）：分页偏移量（默认值：0）format（可选）：响应格式-'markdown'或'json'（默认：'markdown'）
例子：
{
"category": "Öl",
"country": "Sverige",
"max_price": 50,
"limit": 10
}systembolage_get_product
获取特定产品的详细信息。
参数：
product_number（必填）：产品编号（artikelnummer）format（可选）：响应格式-'markdown'或'json'（默认：'markdown'）
例子：
{
"product_number": "12345"
}系统博客_搜索_存储
按名称或位置搜索商店。
参数：
query（可选）：搜索商店名称或位置city（可选）：按城市筛选limit（可选）：结果数量（默认值：20，最大值：100）offset（可选）：分页偏移量（默认值：0）format（可选）：响应格式-'markdown'或'json'（默认：'markdown'）
例子：
{
"city": "Stockholm",
"limit": 5
}发展
运行测试
紫外线：
uv run pytest使用pip/venv：
pytest代码格式化
紫外线：
uv run black systembolaget_mcp.py使用pip/venv：
black systembolaget_mcp.py类型检查
紫外线：
uv run mypy systembolaget_mcp.py使用pip/venv：
mypy systembolaget_mcp.py代码检查
紫外线：
uv run ruff check systembolaget_mcp.py使用pip/venv：
ruff check systembolaget_mcp.py添加依赖关系
紫外线：
uv add
# For dev dependencies:
uv add --dev
使用pip：
# Edit pyproject.toml manually, then:
pip install -e ".[dev]"API密钥提取
此MCP服务器 自动提取API密钥 来自Systembolaget的网站-无需手动配置！
运作原理
服务器使用的技术与 AlexGustafsson/系统公司:
- Fetches Systembolaget的主网站
- 从HTML中提取Next.js应用程序包路径
- 下载应用程序包JavaScript文件
- 提取
NEXT_PUBLIC_API_KEY_APIM价值 - 为后续请求缓存密钥
这种方法之所以有效，是因为Systembolaget的公共网站在前端代码中使用相同的API密钥。
手动配置（可选）
如果您更喜欢使用自定义API密钥，或者如果自动提取失败：
- 访问 api-portal.system bolation.se
- 创建一个帐户并订阅API
- 复制API密钥
- 将其设置为环境变量：
SYSTEMBOLAGET_API_KEY=your-key
服务器将使用您的自定义密钥，而不是自动提取密钥。
建筑
服务器是使用以下方式构建的：
- FastMCP：用于构建MCP服务器的Anthropic Python SDK
- Pydantic v2：用于输入验证和模式生成
- httpx：用于异步HTTP请求
- 键入提示：全程全型安全
设计原则
- 以代理为中心的设计：工具是为完整的工作流而设计的，而不仅仅是API包装器
- API密钥自动提取：无需手动配置-密钥会自动提取
- 错误处理：具有可操作消息的全面错误处理
- 分页：所有列表操作都支持分页以管理大型结果集
- 格式灵活性：人类可读（Markdown）和机器可读（JSON）输出
- 字符限制：截断响应以防止上下文窗口过大
- 缓存：缓存API密钥以最大限度地减少开销
贡献
欢迎投稿！请随时提交拉取请求。
许可证
MIT许可证-有关详细信息，请参阅许可证文件
致谢
- Anthropic 对于MCP SDK
- 系统 公司 API
- AlexGustafsson/系统公司 供API参考
支持
对于问题和疑问：
- 在GitHub上打开一个问题
- 检查 MCP文件
- 查看 Systembolaget API文档