项目简介

Bins API 是一个用于查询英国利兹地区垃圾收集数据的后端服务。它不仅提供常规的REST API，还实现了Model Context Protocol (MCP) 服务器功能，允许大型语言模型（LLM）客户端以标准化的方式查询地址、获取垃圾收集日程及相关页面链接。该服务帮助用户轻松追踪垃圾分类日，并通过LLM实现智能交互。

主要功能点

地址搜索: 根据邮政编码（如 'LS6 2SE'）查询利兹地区的具体地址。
垃圾收集日程查询: 获取指定地址的详细垃圾（如黑色垃圾桶、绿色垃圾桶等）收集日期列表，并标注日期状态（已过期、即将到来、今天）。
地址页面链接获取: 为指定地址生成一个永久链接，该页面包含完整地址、近期收集日程概览、所有收集日期列表、iCal订阅链接及添加日历的说明。
数据自动更新: 定期从开放数据源（利兹市政府）更新垃圾收集数据。
多格式数据导出: 支持JSON、CSV和iCal格式的垃圾收集日程导出。

安装步骤

安装Docker和Docker Compose: 确保您的系统上已安装Docker和Docker Compose。

克隆仓库: 将项目仓库克隆到本地计算机。

git clone https://github.com/imfelixyeung/bins.git
cd bins

配置环境变量: 在项目根目录创建 '.env' 文件，并根据您的环境设置以下变量。
- 'DATABASE_URL': PostgreSQL数据库的连接字符串，例如 'postgresql://user:password@host:port/database'。
- 'tunnel_token': Cloudflare Tunnel 的令牌，用于安全反向代理。如果您在本地开发环境且不使用Cloudflare Tunnel，可以先设置任意值或留空。
- 'RAPID_API_PROXY_SECRET': (可选) 如果您计划通过RapidAPI代理使用，则需要此密钥。
- 'BASE_URL': (可选) 部署的基准URL，例如 'https://bins.felixyeung.com'。
启动服务: 在项目根目录运行 'docker compose up' 命令来启动所有的服务（包括Web应用和数据更新Worker）。
```
docker compose up
```
Web应用（包括MCP服务器接口）通常会在 'http://localhost:3000' 或其他映射端口上运行。

服务器配置

MCP客户端连接此服务器时，需要以下配置信息来建立连接和调用功能。MCP客户端将通过HTTP协议与此MCP服务器通信。

{
  "server_name": "Bins API MCP Server",
  "command": "Next.js",
  "args": ["start"],
  "endpoints": {
    "mcp": {
      "path": "/api/mcp",
      "protocol": "http",
      "host": "localhost",
      "port": 3000
    }
  },
  "description": "连接到利兹地区垃圾收集数据查询的MCP服务器，提供地址搜索、垃圾收集日程和页面链接查询功能。对于部署在 https://bins.felixyeung.com 的实例，MCP端点为 https://bins.felixyeung.com/api/mcp。"
}

'server_name': 服务器的显示名称。
'command': 'Next.js'，表示服务器是一个Next.js应用。
'args': 'start'，Next.js应用的启动命令。
'endpoints.mcp.path': MCP协议的API路径，即 '/api/mcp'。
'endpoints.mcp.protocol': 通信协议，使用 'http'。
'endpoints.mcp.host': 服务器的主机地址，本地运行通常是 'localhost'。
'endpoints.mcp.port': 服务器监听的端口，默认为 '3000'（请根据实际部署调整）。
'description': 对MCP服务器功能的简要描述，供MCP客户端用户参考。请注意，如果部署到生产环境如 'https://bins.felixyeung.com'，您需要将 'host' 和 'port' 替换为 'bins.felixyeung.com' 和 '443' (对于HTTPS)或 '80' (对于HTTP)。

基本使用方法

MCP客户端连接并配置好服务器后，可以通过以下工具与服务器进行交互：

搜索地址: 使用名为 'search_premises_from_postcode' 的工具，提供一个利兹地区的邮政编码作为参数（例如 'postcode: "LS6 2SE"'），以获取匹配的地址列表和其唯一的数字ID。
查询垃圾收集日程: 获得地址ID后，使用名为 'show_premises_jobs_by_id' 的工具，提供地址ID作为参数（例如 'premisesId: 12345'），以获取该地址的垃圾收集日期和垃圾桶类型。
获取地址永久链接: 获得地址ID后，使用名为 'get_premises_permalink' 的工具，提供地址ID作为参数（例如 'premisesId: 12345'），以获取该地址在Bins API网站上的详情页永久链接。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息