荷兰补贴与地址查询服务

Sherlock MCP – 客户端指南 (MCP 服务器)

此 MCP 服务器（“sherlock-mcp”）解锁荷兰 RVO 数据，包括补贴、报告代码/能源设施和地址信息。服务器由 Flowmatic 与合作 技术 荷兰 并作为 FastMCP 服务器在 HTTP 端点后面运行：

• MCP客户端URL: https://sherlock-mcp-351325125041.europe-west4.run.app/mcp
• 验证 ： 需要 API 密钥 –verzend als Bearer代币： Authorization: Bearer <YOUR_API_KEY>

作为 MCP 客户端，您可以看到三种类型的功能：

• 工具 – 功能 （搜索补贴， 通知代码， 地址）
• 资源 – 结构化输出计划， 国家/省/市域列表.
• 提示 – Sherlock 系统提示符，用于人物和指令

下面是如何使用这些元素作为客户端的指南。

1. 连接到 Sherlock MCP 服务器

该服务器作为 FastMCP HTTP 服务器运行，并且可以通过 MCP 在指定的 URL 上访问。

• 在 MCP 客户端（例如 Claude Desktop、VS Code MCP 插件、自定义集成）中：
  • 配置一个 MCP服务器 遇见：
    • url: https://sherlock-mcp-351325125041.europe-west4.run.app/mcp
    • Authorization 头球 Bearer <YOUR_API_KEY>
• 客户端在连接时会自动：
  • initialize 执行
  • tools/list, resources/list, prompts/list 下载
    让我们知道服务器的所有功能。

2. 工具 – 核心功能

服务器提供了一些专门的工具。主要工具：

2.1 health_check

目的：检索服务器状态和数据覆盖/新鲜度。

• 输入（JSON）： HealthCheckInput
  • include_resources: bool – 是否按数据类型需要详细信息（默认： true).
• 输出（JSON）： HealthCheckOutput
  • status: "ok" 的 "degraded"
  • server_name, timestamp
  • storage_mode, storage_detail
  • embedding_enabled
  • resources每个资源记录数，最后刷新，陈旧标志（如果需要）

在客户端中使用：

• 在会话开始时拨打，以检查 RVO 数据是否可用和最新。
• 可在用户界面中显示（最近更新，可用的数据集）。

2.2 address_lookup

目的：通过BAG，Stella Spark Nexus WFS和EP-online将荷兰地址翻译为建筑/纪念碑信息。

• 输入（JSON）： AddressLookupInput

  • postal_code: str | null （string，没有空格，例如。 "1012AB")
  • house_number: int （必填）
  • house_number_addition: str | null （可选等） "A")
  • street_name: str | null – 街道名称， 强制性的，如果没有 postal_code
  • city: str | null 位置名称，如果没有，则必须 postal_code

  注意： 输入或 postal_code 或两者 street_name 英语 city.

• 输出（JSON）： AddressLookupOutput

  • input验证输入的回声
  • timestampUTC 响应时间
  • bag：BAG查找结果（地址+标识）
    • status: "ok", "skipped"，of "error"
    • rd_coordinatesRD（EPSG:28992）坐标 (x, y)
    • ids: nummeraanduiding_id, adresseerbaar_object_id, adresseerbaar_object_type, pand_ids
    • selected选中的 BAG 记录
    • matches所有BAG比赛
    • error错误消息（如果适用）
  • nexusNexus搜索结果（建筑物和纪念碑）
    • status: "ok", "skipped"，of "error"
    • matches：alle Nexus构建单元功能
    • selected：用于纪念碑查找的选定功能
    • monuments: 每个选定的建筑单元的纪念碑功能
    • match_count模糊之前的功能数量
    • error错误消息（如果适用）
  • ep_online：EP在线能源标签查询
    • status: "ok", "skipped"，of "error"
    • selected选定的EP在线记录
    • matches所有EP在线比赛
    • error错误消息（如果适用）
  • warnings非致命警告

2.3 search_rvo_subsidies

目的：RVO补贴目录中的语义搜索工具。

• 输入（JSON）： SubsidySearchInput
  • query: str – 自由文本，例如“热泵角楼2025”（最少3个字符）
  • statuses: list[SubsidyStatus] | null – 状态过滤器 （可选）
    • 可能的值： "Open voor aanvragen", "Bijna open voor aanvragen", "Gesloten voor aanvragen", "Tijdelijk gesloten voor aanvragen"
  • limit: int – 结果的最大数量 （1-50， 默认值： 10）
  • debug: bool – 添加诊断元数据 （默认： false)
• 输出（JSON）： SubsidySearchOutput
  • results补贴清单（id, title, url, score, status)
  • refreshed数据集的最后更新
  • debug诊断元数据（如果需要）

2.4 get_rvo_subsidy

目的：根据ID获取单个RVO补贴的完整详细信息。

• 输入（JSON）： SubsidyDetailInput
  • id: str – 稳定的ID从搜索结果
• 输出（JSON）： SubsidyDetailOutput
  • id, title, url, status, updated_at, categories
  • summary, intro, full_text – 干净的文本字段 （没有 HTML）

2.5 search_rvo_meldcodes

目的：搜索报告代码/安装记录（绝缘、热泵、太阳能锅炉、HR玻璃）。

• 输入（JSON）： MeldcodeSearchInput

  • installation_type: InstallationType – 其中之一：

    • "insulation" （隔离）
    • "zonneboilers"
    • "warmtepompen"
    • "hoogrendementsglas"

    让我们来： "subsidies" 是 没有 允许报告代码搜索 – 用于此目的 search_rvo_subsidies.

  • queries: list[str] – 一个或多个搜索词 （产品名称， 品牌， 类型…）

  • limit: int –每个查询的最大匹配数（1-10，默认值：5）

  • debug: bool – 添加诊断元数据 （默认： false)

• 输出（JSON）： MeldcodeSearchOutput
  • items独特的报告代码项目的dict，按ID索引
    • 每项： merk, type, meldcode, categorie, subsidiabel_vermogen, subsidiebedrag, url
  • results每个查询都有一个匹配对象 query 英语 ids （指向 ID 的列表） items)
  • refreshed最后刷新时间戳
  • debug诊断元数据（如果需要）

2.6 get_meldcode_detail

目的：根据ID获取单个报告代码记录的完整详细信息。

• 输入（JSON）： MeldcodeDetailInput
  • installation_type: InstallationType 如上所述
  • id: str – 稳定的ID从搜索结果
• 输出（JSON）： MeldcodeDetailOutput
  • id, title, url
  • merk, type, meldcode, categorie
  • subsidiabel_vermogen, subsidiebedrag
  • koudemiddel, woningtype, minimale_dikte_mm, biobased
  • intro, full_text – 干净的文本字段 （没有 HTML）

在客户端中调用工具

• 可编程客户端（如FastMCP客户端） list_tools() 发现工具和 call_tool() 使用 JSON 参数调用。
• 在基于 UI 的客户端（如 ChatGPT/Claude）中，llm 可以根据工具说明调用独立的工具。

3. 资源 – 时间表和数据的法学硕士

服务器为计划和支持数据提供各种资源。重要 URI ：

3.1 schema://analyse-schema （分析方案）

目标：结构化的 JSON 架构 分析 输入（报价，发票等）。

包括：

• client_metadata – 公司名称，客户名称，地址，日期等。
• 不同的子弹列表： core_information_bullets, work_description_bullets, financial_overview_bullets, installations_specifications_bullets, omgevingsdata_bullets, timeline_and_execution_bullets
• missing_information – 最多 5 个带标签、提示等的后续查询项目。

在客户端中使用：

• 通过阅读 resources/read het模式在。
• 将此方案用于：
  • 一个 structured output 在您的 LLM 调用中定义（对于 JSON-capable 模型）。
  • 在提示符中生成详细说明（“完全按照此计划”）。

3.2 schema://report-schema （报告模式/报告信封）

目的： JSON 架构 最终报告 （补贴报告）。

结构 ：

• ReportEnvelope 遇见：
  • content (ReportContent):
    • huidige_offerte
    • installaties （包括安装规则和通知代码）
    • subsidie_inzichten （国家/省/市）
    • overige_inzichten
    • samenvatting_en_aanbevelingen （主要规则、差距/风险、后续步骤）

在客户端中使用：

• 作为“最终LLM呼叫”的目标计划：在分析和RVO搜索之后，您可以让LLM完全填写此计划。
• 在用户界面中，您还可以使用此架构在报表文档或 PDF 中动态构建字段和节。

3.3 data://web-search/allowed-domains （允许的域名）

目标：允许网络搜索过滤的域名（包括荷兰市和省）的JSON列表。

用途：

• 如果您的客户端也有自己的 Web 搜索代理，则可以使用此列表将搜索结果列入白名单（仅限 RVO、市、省等）。
• 您可以在客户端显示或缓存列表。

4. 提示符 – Sherlock 的中央系统提示符

服务器还提供可重复使用的提示符模板。

4.1提示 sherlock-system

• 类型：服务器端提示模板
• 目的：给予 canonieke夏洛克系统提示 回归为MCPMessage.
• 文本包括代理人的期望，角色和风格指南。日期 {current_date} 动态填充。
• 输出：
  • 一个 Message 遇见 role="assistant" 和扩展文本（系统级指令）。

在客户端中使用：

• 获取提示 sherlock-system 通过您的 MCP 客户端，并将结果用作 系统提示 您的LLM课程。
• 将其与 JSON 架构资源结合使用：
  • 系统提示 = 角色 + 行为
  • Resource Schema = 所需的输出结构
  • 工具=额外功能。

5.典型的端到端工作流程符合Sherlock MCP

处理报价和补贴调查的典型流程如下：

步骤 1 – 报价分析和地址调查（分析计划）

1. 取得 sherlock-system 并将其用作LLM的系统提示符。
2. 莱斯 schema://analyse-schema 并使用此计划作为目标结构。
3. 让用户上传一个或多个报价/发票。
4. 让您的LLM，通过系统提示符和分析计划发送，报价：
   • 总结成所需的子弹结构，
   • 缺少信息（missing_information),
   • 查找任何设施和地址。
5. 使用找到的地址，在适当的情况下， address_lookup 调用工具并将建筑物/纪念碑上下文添加到分析中。

结果：结构化分析符合JSON schema://analyse-schema地址上下文丰富。

第2步：基于分析的补贴调查

1. 使用分析中的信息（设施，住房类型，背景）构建补贴研究查询。
2. 使用工具：
   • search_rvo_meldcodes 查找报告代码和产品规格；
   • get_meldcode_detail 找到的报告代码的完整细节；
   • search_rvo_subsidies 有关RVO补贴；
   • get_rvo_subsidy 找到补贴的完整细节。
3. 莱斯 data://web-search/allowed-domains 并将此列表作为限制通知您自己的网页搜索代理或LLM，以便仅可靠（特别是荷兰政府/政府相关）域名用于进一步研究。
4. 组合器：
   • ISDE/RVO 数据（通过工具），
   • 允许的域内的任何额外网络搜索结果；
   • 第一步的报价分析 一种统一的补贴形象。

结果：对可能的规则、条件和相关来源的结构化见解。

步骤 3 – 根据报告时间表进行报告

1. 莱斯 schema://report-schema （报告信封）。
2. 使用系统提示符（sherlock-system）再次补充：
   • 步骤 1 中的 JSON 分析
   • 步骤2中的补贴见解，
   • 任何额外的说明（例如风格或目标受众）。
3. 让您的LLM生成完全符合的报告 schema://report-schema包括：
   • 描述当前情况/报价，
   • 设施概览，包括报告代码和金额，
   • 补贴的见解（国家/省/市），
   • 总结和建议。
4. 直接在应用程序中使用生成的报告（例如，作为 PDF、客户演示文稿或仪表板的基础 ） 。

在每个阶段，它的工作 sherlock-system 提示作为底层系统提示：他设置了LLM的角色，语气和方法。此外，您还可以添加额外的用户/助理消息，以便将此流程注入聊天机器人或其他标准化工作流程。

6. 身份验证和安全性

• 需要 API 密钥认证 所有请求都必须包含有效的 API 密钥。
• 将API密钥作为Bearer令牌发送到 Authorization 头球 Authorization: Bearer <YOUR_API_KEY>

7. 摘要 – 如何将此MCP用作客户端？

• 使用 URL 配置 MCP 客户端。
• 添加 Authorization 头部趾部： Bearer <YOUR_API_KEY>.
• 使用 提示:
  • 获取 sherlock-system 并将其用作LLM的系统提示符。
• 使用 资源:
  • 莱斯 schema://analyse-schema 英语 schema://report-schema 严格结构化您的LLM输出。
  • 可选：已使用 data://web-search/allowed-domains om网络搜索过滤器。
• 使用 工具:
  • health_check 为了状态。
  • address_lookup 地址 → 建筑物/纪念碑/能源标签数据。
  • search_rvo_subsidies 英语 get_rvo_subsidy 关于RVO补贴的实质性信息。
  • search_rvo_meldcodes 英语 get_meldcode_detail 报告代码/安装信息。

8. FastMCP客户端 – 从Python使用Sherlock MCP

除了通用的 MCP 客户端（Claude Desktop、ChatGPT 等），您还可以通过 FastMCP客户端 (fastmcp.Client）。这为您提供了一个简单，可编程的界面来调用工具，资源和提示。

8.1 基本例子

下面的示例演示了如何连接到 Sherlock MCP 服务器、获取可用功能并运行健康检查：

import asyncio
from fastmcp import Client
from httpx import AsyncClient

async def main() -> None:
    # Configureer HTTP client met authenticatie header
    http_client = AsyncClient(
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    client = Client(MCP_URL, http_client=http_client)

    async with client:
        # Controleren of de server bereikbaar is
        await client.ping()

        # Basis-capabilities ophalen
        tools = await client.list_tools()
        resources = await client.list_resources()
        prompts = await client.list_prompts()

        print("Tools:", [t.name for t in tools.tools])
        print("Resources:", [r.uri for r in resources.resources])
        print("Prompts:", [p.name for p in prompts.prompts])

        # Voorbeeld: health_check tool uitvoeren
        health = await client.call_tool("health_check", {"include_resources": True})
        print("Health status:", health.data)

asyncio.run(main())

你可以在同一个会话中使用工具、资源和提示符，这正是Sherlock MCP的三个基石。

8.1.1 发现工具

使用 list_tools() 下载所有Sherlock MCP工具：

from fastmcp import Client

async with Client(MCP_URL, http_client=http_client) as client:
    tools = await client.list_tools()
    for tool in tools.tools:
        print("Tool:", tool.name)
        print("Beschrijving:", tool.description)
        if tool.inputSchema:
            print("Parameterschema:", tool.inputSchema)

您可以按标签过滤，例如仅显示“分析”工具：

async with Client(MCP_URL, http_client=http_client) as client:
    tools = await client.list_tools()

    analyse_tools = [
        t for t in tools.tools
        if getattr(t, "meta", None)
        and "_fastmcp" in t.meta
        and "analysis" in t.meta["_fastmcp"].get("tags", [])
    ]

    print("Analyse-tools:", [t.name for t in analyse_tools])

注：它 meta._fastmcp块是FastMCP协议；它可以根据服务器配置启用/关闭。

8.1.2 使用工具

一个工具呼吁你 call_tool(name, arguments=...):

from fastmcp import Client

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.call_tool(
        "search_rvo_subsidies",
        {"query": "warmtepomp hoekwoning 2025", "limit": 5},
    )
    print(result.data)

您还可以提供高级选项，例如 timeout 或具体的 progress_handler:

async def my_progress_handler(progress: float, total: float | None, message: str | None) -> None:
    print(f"{progress}/{total} - {message}")

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.call_tool(
        "search_rvo_meldcodes",
        {"installation_type": "warmtepompen", "queries": ["Nefit EnviLine 6 kW"], "limit": 3},
        timeout=5.0,
        progress_handler=my_progress_handler,
    )

达尔奈斯特·昆杰 meta 跟踪或客户信息：

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.call_tool(
        "health_check",
        {"include_resources": True},
        meta={"trace_id": "abc-123", "client": "sherlock-dashboard"},
    )

8.1.3 读取结果（CallToolResult）

call_tool() 返回一个 CallToolResult 有三个主要方面：

• result.data – FastMCP 独家基于输出方案（包括 datetimes、enums、自定义 Pydantic 模型等）的完全水合 Python 对象。
• result.structured_content 原始结构化JSON（标准MCP）。
• result.content – 标准 MCP 内容块（文本等）列表。

在实践中，使用Sherlock工具几乎总能 result.data 使用：

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.call_tool(
        "health_check",
        {"include_resources": True},
    )

    health = result.data  # reeds omgezet naar het HealthCheckOutput-model
    print("Status:", health.status)
    print("Server:", health.server_name)
    print("Timestamp:", health.timestamp)

8.1.4 工具错误处理

标准投 call_tool() 一 ToolError 工具故障：

from fastmcp import Client
from fastmcp.exceptions import ToolError

async with Client(MCP_URL, http_client=http_client) as client:
    try:
        result = await client.call_tool("potentially_failing_tool", {"param": "value"})
        print("OK:", result.data)
    except ToolError as exc:
        print("Tool mislukt:", exc)

8.1.5通过客户端访问资源（模式的en数据）

资源是Sherlock MCP暴露的数据源。对于夏洛克来说，尤其是：

• schema://analyse-schema 分析结构的 JSON 架构。
• schema://report-schema – 报表结构的 JSON 架构。
• data://web-search/allowed-domains JSON 允许的域名

您正在探索资源 list_resources():

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.list_resources()
    for resource in result.resources:
        print("URI:", resource.uri)
        print("Naam:", resource.name)
        print("Beschrijving:", resource.description)
        print("MIME-type:", resource.mimeType)

阅读资源内容

遇见 read_resource(uri) 阅读一个资源的内容：

import json

async with Client(MCP_URL, http_client=http_client) as client:
    contents = await client.read_resource("schema://analyse-schema")
    for item in contents:
        text = getattr(item, "text", None)
        if text is not None:
            print("MIME-type:", item.mimeType)
            schema = json.loads(text)
            print("Top-level keys:", schema.keys())

对于 Sherlock 资源，内容是文本 JSON （mimeType="application/json"所以你可以直接分析它们。对于二进制内容（例如图像），您可以 item.blob 使用并自行写入磁盘。

资源模板

FastMCP还支持“资源模板”（带参数的URI模式） list_resource_templates() 英语 read_resource() 使用填充的模板 URI。Sherlock 目前没有定义模板，但通用客户端仍然可以处理：

async with Client(MCP_URL, http_client=http_client) as client:
    templates = await client.list_resource_templates()
    print("Templates:", [t.uriTemplate for t in templates.templates])

在多服务器客户端中，URI通常以服务器名称（每个客户端约定）前缀，例如： sherlock:schema://analyse-schema – 查看 FastMCP 客户端文档以查看确切的模式。

8.1.6客户端提示

提示符是服务器提供的可重复使用的提示符模板。至少，夏洛克有 sherlock-system prompt（中央系统提示符），但客户端 API 对所有提示符都是通用的。

发现提示

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.list_prompts()
    for prompt in result.prompts:
        print("Prompt:", prompt.name)
        print("Beschrijving:", prompt.description)
        if prompt.arguments:
            print("Argumenten:", [arg.name for arg in prompt.arguments])

在LLM流中使用提示符

遇见 get_prompt(name, arguments) 请求服务器将提示符渲染为 MCP 消息列表：

async with Client(MCP_URL, http_client=http_client) as client:
    # Sherlock system prompt ophalen
    result = await client.get_prompt("sherlock-system", {})

    for message in result.messages:
        print("Rol:", message.role)
        print("Content:", message.content)

返回的 messages 您可以直接将系统/助理/用户消息传递给您的 LLM 客户端（OpenAI、Anthropic 等）。

带参数和自动序列化的提示符

如果 prompt 接受参数，则将其作为 dict 提供。FastMCP 会根据 MCP 规范自动将复杂值序列化为 JSON 字符串，以便服务器可以将其解析为类型对象：

from dataclasses import dataclass

@dataclass
class UserContext:
    name: str
    segment: str

async with Client(MCP_URL, http_client=http_client) as client:
    result = await client.get_prompt(
        "analyse_offerte",
        {
            "user": UserContext(name="Alice", segment="zakelijk"),
            "config": {"include_subsidies": True, "language": "nl"},
            "title": "Analyse van offerte 123",
        },
    )

    for msg in result.messages:
        print(msg.role, ":", msg.content)