Secil Canary Historian MCP服务器

模型上下文协议（MCP）服务器为LLM驱动的应用程序提供对Canary Historian工厂数据的无缝访问。

概述

通用Canary MCP服务器使LLM客户端（Claude Desktop、Continue等）能够通过自然语言查询与Canary Historian工业数据进行交互。该服务器实现MCP协议标准，公开了允许工程师和分析师访问实时和历史工厂数据的工具，而无需手动集成API。

项目状态： MVP已实施| Secil Cement Maceira现场得到支持|迫击炮得到支持| Outão现场正在进行中

快速链接：

API合同（本地文档和安全说明）：参见下文“API合同（本地文件）”。

特性

✅ MCP协议实现 -基于FastMCP的服务器，带有工具注册功能
✅ Ping工具 -连接测试和健康检查
✅ 环境配置 -通过环境变量灵活配置
✅ 本地标记词典 -Canary导出的脱机索引种子保持了自然语言标记映射的可靠性，即使在API搜索未命中的情况下也是如此
✅ 自动标签分辨率 -短标识符（例如 P431)透明地解析所有工具中完全合格的Canary路径
✅ 综合测试 --单元/集成套件加上自动健康检查
✅ Canary API集成 -故事1.2
✅ 数据访问工具 -进入故事1.3-1.7

安装

支持两种传输模式，两者都可以在没有管理员权限的情况下工作：

模式	传输	何时使用	安装入口点
本地STDIO（默认）	MCP客户端和此仓库之间的STDIO管道	单个笔记本电脑，气隙测试，最快迭代	运行 `scripts/Install-Canary-MCP.cmd` （包裹 `deploy_canary_mcp.ps1`)或遵循非管理员Windows指南无需标高。
远程HTTP/SSE	带有SSE流的HTTP服务器	团队共享VM或容器部署	在服务器/VM上使用相同的仓库并公开端口6000（请参阅远程HTTP部署).

STDIO验证检查表

双击 Install-Canary-MCP.cmd （或奔跑 deploy_canary_mcp.ps1)并在提示时提供Canary URL。
脚本完成后，重新打开Claude Desktop（或您的MCP客户端）并运行 ping 工具。成功消息：“pong–Canary MCP服务器正在运行！”
如果 ping 失败，请重新运行安装程序 --verbose 或咨询 docs/troubleshooting/DEBUG_MCP_SERVER.md.

要通过uv进行手动配置，请跳到快速设置（uv）.

MCP服务器功能

Canary MCP服务器为与Canary Historian交互提供了丰富的功能。这些分为工具、提示（工作流）和资源。

访问控制

对MCP服务器的访问使用OAuth 2.0进行保护，OAuth 2.0是行业标准的授权协议。MCP客户端必须提供有效的承载令牌才能访问服务器的资源。

Canary API身份验证

对基础Canary API的身份验证由服务器透明地处理。这 CANARY_API_TOKEN 必须使用有效的API令牌设置环境变量，服务器使用该令牌与Canary Historian进行所有通信。

工具

工具是可以由MCP客户端直接执行的功能。

ping() -健全性检查MCP是否可访问。在会话开始前使用；它从不碰金丝雀。
get_asset_catalog() –快速离线查看策划的标签目录。非常适合仅发现元数据或Canary脱机时使用。响应遵循1 MB护栏，必要时在引导下截断。
search_tags(search_pattern) –当您已经知道标签名称的一部分时，可以实时浏览Canary。避免使用通配符；与...配对 get_tag_path 对于NL流。
get_tag_metadata(tag_path) –一旦你知道完全限定的路径，就可以获取详细的属性（单位、eng限制、描述）。陷阱：需要精确的历史学家路径；使用 get_tag_path 首先解析别名。
get_tag_path(description) –NL→ 历史路径工作流。退货 confidence, confidence_label，以及 clarifying_question 因此LLM知道何时继续或向用户询问更多上下文。
get_tag_properties(tag_paths) –对多个路径进行批量属性查找。在发出大型读取查询之前交叉检查单元时很方便。
list_namespaces() –发现命名空间根目录/文件夹。使用此功能确认植物的结构或为UI拾取器播种。
get_last_known_values(tag_names) –获取一个或多个标签的最新样本。如果请求的窗口中不存在数据，则自动回退到配置的视图。
read_timeseries(tag_names, start_time, end_time) –历史数据的规范路径。接受ISO时间戳或Canary相对表达式；观看 continuation 寻呼令牌。
get_tag_data2(tag_names, start_time, end_time, aggregate_name?, aggregate_interval?, max_size?) –高容量的兄弟姐妹 read_timeseries 它击中了金丝雀 getTagData2 终点。当您希望减少连续跳数时，请将其用于大型窗口或服务器端聚合（调优 max_size).
get_aggregates(), get_asset_types(view?), get_asset_instances(asset_type, view?, path?), get_events_limit10(limit?, …), browse_status(path?, depth?, include_tags?, view?) –Canary Views资产/事件以及命名空间检查的元数据助手。使用 browse_status 要漫游视图层次结构，请确认 nextPath，并验证 tags/nodes 在进行更重的搜索之前，有效载荷。
write_test_dataset(dataset, records, original_prompt, role, dry_run=False) –通往Canary SAF API的门控写入路径。仅 Test/Maceira 和 Test/Outao 允许使用数据集，调用者必须传递测试人员角色（默认为 tester).使用 dry_run=True 在发送和保存之前验证有效载荷 records 在...之下 CANARY_MAX_WRITE_RECORDS 限制。
get_server_info() –报告Canary功能（时区、聚合）和MCP设置。部署后运行它，以确保环境连接正确。
get_metrics() / get_metrics_summary() –Prometheus输出与人类可读的请求计数、延迟、缓存统计摘要。用于健康仪表板或快速CLI检查。
get_cache_stats(), invalidate_cache(pattern), cleanup_expired_cache() –调试过时数据时管理本地元数据缓存。
get_health() –整合MCP/断路器状态以及缓存/指标快照。将其连接到操作监视器，以获得高级心跳。

提示（工作流）

提示是结构化的、多步骤的工作流程，指导LLM或MCP客户端完成复杂的流程。

tag_lookup_workflow：将自然语言请求（例如“主窑温度”）翻译成精确的Canary标签路径的指导性工作流程。它精心策划了 get_asset_catalog, search_tags，以及 get_tag_properties，并发出置信度/澄清问题信号，以便LLM知道何时与用户再次确认。
timeseries_query_workflow：用于安全有效地检索历史数据的确定性工作流程。在将结果总结回用户之前，它将遍历标签解析、自然语言时间解析、有效载荷组装和连续处理。

看 docs/workflows/prompt-workflows.md 获取完整的分步剧本，包括输入、输出和示例对话。

资源

资源向MCP客户端提供静态数据或文档，以帮助构建有效的查询。

maceira_tag_catalog：一个JSON资源，包含Maceira网站的精选标签列表，包括自然语言描述和工程单位。这是标签发现的主要参考。
canary_time_standards：一个JSON资源，为Canary的相对时间表达式（例如“Now-1d”）和服务器的默认时区提供参考指南(Europe/Lisbon).
参考文件：参见 docs/resources/resource-index.md 对于每个磁盘上的工件（标签目录、时间标准、Postman导出）以及RAG可行性说明和尺寸护栏提醒。

仅元数据标记发现

您可以在不接触Canary API的情况下通过组合本地资源来解析标签：

呼叫 get_asset_catalog /阅读 resource://canary/tag-catalog 获取候选路径、描述和单位。
使用 get_local_tag_candidates （从 src/canary_mcp/tag_index.py)根据您的关键字对目录条目进行评分。
将结果输入 get_tag_path，现在正在发射 confidence, confidence_label，以及 clarifying_question 字段，以便LLM知道是否继续(confidence ≥ 0.80)或者询问更多上下文。
将响应保持在1以下 MB护栏(CANARY_MAX_RESPONSE_BYTES，默认值1 000 000). 如果响应被截断，则有效载荷包括预览和缩小查询范围的指导。

MCP客户端/LLM的预期工作流程

为了有效地与Canary Historian交互，MCP客户端和LLM应遵循利用服务器功能的结构化工作流程。服务器提供引导 提示（工作流） 和静态资源以确保可靠和高效的数据访问。

标签发现：要查找特定标签，客户端应使用 tag_lookup_workflow。此提示会协调使用以下工具 get_asset_catalog 和 search_tags 连同 maceira_tag_catalog 资源将用户的请求（例如“主窑温度”）转换为完全合格的Canary标签路径。

数据检索：一旦标识了标签路径，客户端应使用 timeseries_query_workflow。此提示可确保正确指定时间范围（参考 canary_time_standards)而且 read_timeseries 使用有效参数调用工具以获取历史数据。

双语关键字搜索和域名上下文：搜索时，将英语关键字与葡萄牙语同义词配对，特别是葡萄牙语网站（Maceira、Outão、Pataias、Montijo、Rio Maior和Martingança），并翻译用户的自然语言提示，以提取重要的关键标签、变量和历史位置。请记住，数据库存储工业过程数据（PLC、温度传感器、压力变送器等），这些数据在每周或每月等间隔内被归一化、处理、过滤或聚合为有意义的指标和KPI；这种背景指导了更好的工程、性能、维护、质量和合规决策。

通过遵循这些工作流程，客户端可以可靠地导航Canary Historian，解决歧义，并高效地检索数据，从而抽象出底层API的复杂性。

快速设置（uv）

在Windows、macOS或Linux上使用uv在本地运行的快速路径。

先决条件：

PATH上提供Python 3.12或3.13（可移植Python在Windows上工作）
紫外线已安装

步骤：

# 1) Install uv (one-time)
# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS/Linux
curl -fsSL https://astral.sh/uv/install.sh | sh

# 2) Clone and enter repo
git clone 
cd BD-Canary-MCP

# 3) Create and activate virtual env + install deps
uv sync --locked --dev

# 4) Configure environment from template
copy .env.example .env  # Windows
# or
cp .env.example .env    # macOS/Linux
# Then edit .env with your Canary credentials (no secrets committed)

uv run pip install .

# 5) Validate installation
uv run python scripts/validate_installation.py

# 6) Start the MCP server
uv run canary-mcp
# or
uv run python -m canary_mcp.server

笔记：

使用python-dotenv从.env加载配置。
使用uv run pytest执行测试；uvx褶边/黑色用于棉绒/格式化。
有关Claude Desktop集成，请参阅下面的部分。

建筑

BD-hackaton-2025-10/
├── src/
│   └── canary_mcp/          # Main MCP server package
│       ├── __init__.py      # Package initialization
│       └── server.py        # MCP server with tool definitions
├── tests/
│   ├── unit/                # Unit tests
│   │   └── test_project_structure.py
│   └── integration/         # Integration tests
│       └── test_mcp_server_startup.py
├── config/                  # Configuration files
├── docs/                    # Project documentation
├── pyproject.toml          # Python project metadata & dependencies
├── .env.example            # Environment variable template
└── README.md               # This file

组件体系结构

┌─────────────────────────────────────────┐
│   LLM Client (Claude Desktop, etc.)    │
└────────────────┬────────────────────────┘
                 │ MCP Protocol
                 ↓
┌─────────────────────────────────────────┐
│      Universal Canary MCP Server        │
│  ┌───────────────────────────────────┐  │
│  │  FastMCP Server                   │  │
│  │  - Tool Registration              │  │
│  │  - Request Handling               │  │
│  └───────────────────────────────────┘  │
│  ┌───────────────────────────────────┐  │
│  │  MCP Tools                        │  │
│  │  - ping (connection test)         │  │
│  │  - [Canary data tools]    │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
                 ↓ (Future)
┌─────────────────────────────────────────┐
│      Canary Views Web API               │
│  - Authentication                       │
│  - Historical Data Access               │
│  - Real-time Data Streaming             │
└─────────────────────────────────────────┘

部署

现在支持三种部署模式。选择适合您工作流程的一个，并按照链接的指南查看完整的剧本。

选项	运输	最适合	文件
本地MCP（STDIO）	STDIO	开发人员笔记本电脑，单机分析	部署摘要
远程MCP（HTTP SSE）	HTTP+SSE	共享VM（例如。 `vmhost8.secil.pt`)，部门推出	远程HTTP部署
容器化MCP	HTTP+SSE	Docker/Podman、CI/CD、Kubernetes	集装箱导轨

本地STDIO快速入门

uv sync --locked --dev
cp .env.example .env  # set CANARY_MCP_TRANSPORT=stdio and credentials
uv run python -m canary_mcp.server

在MCP客户端中尝试此操作

在Claude Desktop（或其他MCP客户端）中，启动新的聊天并运行以下步骤：

加载ISA‑95/UNS指南资源，以便模型理解工厂结构和命名：

read_resource("resource://canary/uns-tag-guide")

问一个依赖于该上下文的自然语言问题。例如：

“Using the UNS guide you just read, identify the correct Canary tag paths for Kiln 6 main burner temperature at Maceira and show a 24‑hour trend ending now with 5‑minute granularity. Return the chosen tag paths and a short rationale for each mapping.”

提示：如果模型不确定，它应该调用 get_asset_catalog 或 search_tags 并在继续之前提出一个澄清问题。

远程HTTP SSE快速入门

# edit .env on the server
CANARY_MCP_TRANSPORT=http
CANARY_MCP_HOST=0.0.0.0
CANARY_MCP_PORT=6000

# then launch
uv run python -m canary_mcp.server

通过以下方式验证侦听器：

scripts/check_mcp.sh http http://vmhost8.secil.pt:6000

容器快速启动

docker compose up --build
# or
podman-compose up --build

注入 .env 通过环境变量或绑定挂载，并根据需要将容器放置在企业入口后面。

示例 `.env` 条目（复制自 `.env.example`)

# Transport (stdio keeps everything local)
CANARY_MCP_TRANSPORT=stdio
# Canary endpoints (read & write)
CANARY_SAF_BASE_URL=https://scunscanary.secil.pt/api/v1
CANARY_VIEWS_BASE_URL=https://scunscanary.secil.pt
# Optional: default view scoping for read_timeseries
CANARY_DEFAULT_VIEW=Secil.Portugal.Default
# Asset metadata view for get_asset_types / get_asset_instances
CANARY_ASSET_VIEW=Views/Maceira.Assets
# Token issued in Canary Identity (Tag Security applies)
CANARY_API_TOKEN=00000000-0000-0000-0000-000000000000
# Write tool guardrails
CANARY_WRITER_ENABLED=true
CANARY_TESTER_ROLES=tester,qa
CANARY_WRITE_ALLOWED_DATASETS=Test/Maceira,Test/Outao
# Vector/RAG knobs (optional)
CANARY_ENABLE_VECTOR_SEARCH=false
CANARY_VECTOR_INDEX_PATH=data/vector-index
CANARY_VECTOR_TOP_K=5
CANARY_VECTOR_DIM=512
CANARY_VECTOR_HASH_SEED=0

集 CANARY_MCP_TRANSPORT=http 加 CANARY_MCP_HOST/CANARY_MCP_PORT 当您将同一版本升级到远程VM时。

需要令牌或标签安全复习吗？看 API合同（本地文档）获取内部Canary读/写PDF的链接 docs/aux_files/Canary API.

API合同（本地文档）

地点： docs/aux_files/Canary API

- 阅读（视图）API：“Canary Labs Historian Views Service API文档（v25.4）” - 编写（存储和转发）API：“Canary Labs Historian存储和转发服务API文档（v25.3）”

身份验证和标签安全

- 使用 apiToken （在Canary Identity中配置）用于所有API调用。每个令牌都映射到一个Canary用户。 - 如果启用了标记安全，Canary用户必须具有视图的读取权限（read）和目标数据集的写入权限（write）。 - 对于通过SaF写入，如果服务远离Historian，则也使用API令牌配置SaF服务。 - 向后兼容性：一些端点接受 accessToken 如果 apiToken 未提供； /getUserToken 当凭据链接到Identity用户时，仍用于传统流。

项目策略：WRITE工具被选为 Test/* 仅数据集（例如。， Test/Maceira, Test/Outao).帮助者 canary_mcp.write_guard.validate_test_dataset 在将任何有效载荷发送到Canary之前强制执行此规则。

请求示例（读/写）

READ（视图）--getTagData

- 端点： POST {VIEWS_BASE}/api/v2/getTagData - 主体（示例）：

    {
      "apiToken": "",
      "tags": ["Maceira.Cement.Kiln6.Temperature.Outlet"],
      "startTime": "2025-10-30T00:00:00Z",
      "endTime": "2025-10-31T00:00:00Z",
      "pageSize": 1000
    }

- 回复（形状摘录）：

    {
      "data": [
        {"timestamp": "2025-10-30T12:00:00Z", "value": 26.2, "quality": "Good", "tagName": "...Outlet"}
      ]
    }

WRITE（存储和转发）--会话和写入示例

- 会话（令牌创建流程取决于部署；请参阅SaF文档） - 可选设置 autoCreateDatasets": true 用于测试环境。 - 写请求（概念示例，具体模式请参见SaF v25.3）：

    {
      "apiToken": "",
      "dataSet": "Test/Maceira",
      "points": [
        {"path": "Test/Maceira/MCP.Telemetry.Success", "timestamp": "2025-10-31T12:00:00Z", "value": 1}
      ]
    }

用法

使用MCP检查员进行测试

使用MCP检查器在没有客户端的情况下交互式测试服务器：

npx @modelcontextprotocol/inspector uv --directory . run canary-mcp

这将在浏览器中启动Inspector UI，并通过uv从当前目录启动服务器。

运行MCP服务器

# Start the server
uv run canary-mcp

# Or run directly
uv run python -m canary_mcp.server

运行测试

# Run all tests
uv run pytest

# Run unit tests only
uv run pytest -m unit -q

# Run integration tests only (using pytest)
uv run pytest -m integration -q

# Run integration tests with a specific environment (as used in CI)
python scripts/run_integration_tests.py --env test

CLI工具验证器

使用捆绑的脚本来练习主要的MCP工具（在缺少凭据时跳过网络相关的调用）：

python scripts/test_mcp_tools.py \
  --sample-tag "Maceira.Cement.Kiln6.Temperature.Outlet" \
  --search-pattern "Kiln*Temp"

操作烟雾脚本

针对运维/SRE用例的快速一次性测试：

脚本	目的
`python scripts/run_get_metrics.py`	转储普罗米修斯公开字符串
`python scripts/run_get_cache_stats.py`	显示缓存命中/未命中计数和条目总数。
`python scripts/run_cleanup_expired_cache.py`	强制执行缓存清理周期并打印摘要。
`python scripts/run_get_health.py`	发射合并的MCP健康有效载荷（断路器、缓存、指标）。
`python scripts/run_get_events_limit10.py`	使用可选的视图/时间过滤器获取最近的历史事件。
`python scripts/run_get_tag_data2.py`	检索用户指定时间窗口的标记样本/聚合。
`python scripts/run_invalidate_cache.py`	清除与可选模式匹配的元数据缓存条目。
`python scripts/run_write_test_dataset.py`	干运行（或执行）写入 `Test/*` 数据集；需要SAF配置。
`python scripts/run_browse_status.py`	遍历命名空间层次结构，返回 `nodes`/`tags` 和 `nextPath` 提示。

参见 docs/development/manual-tool-scripts.md 此表中每个脚本的CLI文档和环境要求。

书写测试遥测（测试/Meseira+测试/Outao）

构建有效载荷 –每条记录都需要在允许的测试数据集下有一个完全限定的标签、一个数值和（可选）一个ISO时间戳。缺少的时间戳默认为“现在”（UTC）。
先进行试运行 –设置 dry_run=true 在接触Canary之前，验证数据集、角色和有效载荷大小。
仅限测试人员 –the role 参数必须匹配 CANARY_TESTER_ROLES （默认为 tester).不匹配的角色收到403响应。
清理指导 –使用Canary的 /deleteRange 端点或历史用户界面，以在实验后删除测试数据。因为写作仅限于 Test/*，生产数据集保持不变。

MCP有效载荷示例：

{
  "tool": "write_test_dataset",
  "args": {
    "dataset": "Test/Maceira",
    "records": [
      {
        "tag": "Test/Maceira/MCP.Audit.Success",
        "value": 1,
        "timestamp": "2025-11-07T23:00:00Z"
      }
    ],
    "original_prompt": "Log that the kiln temperature sanity check succeeded.",
    "role": "tester",
    "dry_run": true
  }
}

翻转 dry_run 到 false 一旦预览看起来正确。响应与捕获的提示、角色和记录详细信息相呼应，以供审计。

矢量索引/RAG管道（可选）

构建JSONL+嵌入

   python scripts/build_vector_index.py \
     --source "docs/aux_files/Canary Resources/Canary_Path_description_maceira.json" \
     --out data/vector-index

- 生产 catalog.jsonl, embeddings.npy, records.json，以及 meta.json. - 使用基于哈希的确定性嵌入（可通过以下方式配置 CANARY_VECTOR_DIM / --dimension)因此可以在没有外部服务或GPU依赖性的情况下重建索引。

启用语义搜索

   CANARY_ENABLE_VECTOR_SEARCH=true
   CANARY_VECTOR_INDEX_PATH=data/vector-index
   CANARY_VECTOR_TOP_K=5

把这些放进去 .env当启用时， get_local_tag_candidates 使用顶级语义匹配来增加关键字点击量（仍以1为上限 MB有效载荷保护）。

重建节奏

- 每当目录JSON发生变化时，请重新运行脚本。 - 结果 data/vector-index/ Git会忽略该目录；如果需要共享索引，请单独存档。

语义建议是累加的——倒排索引仍然是真理的来源，向量匹配包括 "source": "vector-index" 元数据，以便MCP客户端可以解释每个候选的来源。

该脚本打印人类可读的PASS/WARN/FAIL摘要，并遵守全局1 MB响应护栏。

测试Ping工具

# Python interactive test
from canary_mcp.server import ping

# Call the ping tool function
response = ping.fn()
print(response)
# Output: "pong - Canary MCP Server is running!"

连接到克劳德桌面

使用此MCP服务器的主要方式是通过Claude Desktop。按照以下步骤进行连接：

1.找到Claude桌面配置文件

配置文件位于：

%APPDATA%\Claude\claude_desktop_config.json

完整路径（Windows）：

C:\Users\\AppData\Roaming\Claude\claude_desktop_config.json

2.添加MCP服务器配置

创建或编辑具有以下内容的配置文件：

{
  "mcpServers": {
    "canary-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Github\\BD\\BD-hackaton-2025-10",
        "run",
        "python",
        "-m",
        "canary_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "C:\\Github\\BD\\BD-hackaton-2025-10\\src"
      }
    }
  }
}

重要提示：

替换 C:\\Github\\BD\\BD-hackaton-2025-10 使用您的实际项目路径
使用双反睫毛(\\)JSON格式的Windows路径
需要克劳德桌面0.7.0+版本（MCP支持）

3.重新启动克劳德桌面

完全关闭Claude Desktop（检查系统托盘）并重新启动。MCP服务器现在应该已连接。

4.验证连接

在Claude Desktop中，您应该看到：

MCP服务器指示灯显示“已连接”状态
“金丝雀mcp服务器”列在可用服务器中
界面中的可用工具

5.使用MCP工具

您现在可以使用自然语言与Canary Historian数据进行交互：

"Use the list_namespaces tool to show me available Canary namespaces"

"Use the search_tags tool to find all temperature sensors"

"Use the read_timeseries tool to get data for tag 'Secil.Line1.Temperature'
from yesterday to now"

"Use the get_server_info tool to check the Canary server connection"

可用的MCP工具

ping -测试MCP服务器连接
list_namespaces -浏览Canary层次结构
search_tags -通过模式匹配查找标签
提示： 使用时 search_tags，提供文字标识符（例如 P431)不附加通配符-Canary API在内部处理模糊匹配。
get_tag_metadata -获取详细的标签信息
get_tag_properties -检索标签的原始工程属性和历史元数据
read_timeseries -查询历史时间序列数据
get_server_info -检查Canary服务器运行状况和信息

详细设置指南： 看 docs/installation/claude-desktop-setup.md

配置

配置是通过环境变量进行管理的。复制 .env.example 到 .env 并自定义：

# Required: Canary API Configuration
CANARY_SAF_BASE_URL=https://scunscanary.secil.pt/api/v1
CANARY_VIEWS_BASE_URL=https://scunscanary.secil.pt
CANARY_API_TOKEN=your-token-here
CANARY_TAG_SEARCH_ROOT=Secil.Portugal
CANARY_TAG_SEARCH_FALLBACKS=
CANARY_LAST_VALUE_LOOKBACK_HOURS=24
CANARY_LAST_VALUE_PAGE_SIZE=500

# Optional: Server Configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=6000

# Optional: Logging
LOG_LEVEL=INFO

# Optional: Performance Settings
CANARY_TIMEOUT=30
CANARY_POOL_SIZE=10
CANARY_RETRY_ATTEMPTS=6

关键配置变量：

CANARY_SAF_BASE_URL -Canary SAF（存储和转发）API的基本URL
CANARY_VIEWS_BASE_URL -Canary Views的基本URL API
CANARY_API_TOKEN -身份验证令牌（必填，请保密！）
CANARY_TAG_SEARCH_ROOT -调用时使用的根命名空间 browseTags （例如 Secil.Portugal)
CANARY_TAG_SEARCH_FALLBACKS -用于探测根作用域为空时的其他命名空间前缀（逗号分隔）
CANARY_LAST_VALUE_LOOKBACK_HOURS -检索上次已知值时使用的窗口（小时）
CANARY_LAST_VALUE_PAGE_SIZE -解析上一个值所需的最大样本数
LOG_LEVEL -日志详细程度：调试、信息、警告、错误、严重
CANARY_TIMEOUT -请求超时（秒）（默认值：30）
CANARY_RETRY_ATTEMPTS -失败请求的重试次数（默认值：6）

看 .env.example 有关可用配置选项的完整列表，包括性能调优、断路器设置和会话管理。

文档

综合文档可在 docs/ 目录：

API 参考

API文档（docs/nenenebb API.md） -所有MCP工具的完整参考：

核心数据访问工具：搜索标签、获取标签元数据、读取时间序列、列表名称空间、获取服务器信息
性能和监控工具：get_metrics，get_metrics_summary
缓存管理工具：get_cache_stats、无效缓存、清理扩展缓存
错误代码：身份验证、连接、超时、断路器错误
最佳实践：缓存策略、性能优化、查询模式

查询示例

示例查询库（docs/examples.md） -20多个真实世界的例子，涵盖：

验证用例：传感器验证、交叉验证、数据质量检查
故障排除用例：异常诊断、模式识别、性能比较
优化用例：操作设定点优化、能源浪费检测、稳定性分析
报告用例：每日报告、合规报告、交接班
集成示例：维护警报、预测性维护、能源管理

其他文件

部署指导 -完成站点部署和部署程序
建筑 -系统架构和设计决策
多站点配置 -管理多个Canary网站
故障排除指南 -常见问题和解决方案
PRD和Epics -产品要求和功能规划

快速链接

"Find all temperature sensors for Kiln 6"
→ See examples.md: Example 1 (Sensor Validation)

"Show me performance from yesterday"
→ See examples.md: Example 6 (Historical Comparison)

"What tools are available?"
→ See API.md: Core Data Access Tools

发展

项目结构

src/金丝雀\_ mcp/ -主要应用代码
测试/ -测试套件（单元和集成）
docs/ -文档（PRD、史诗、故事）
config/ -配置文件

开发工作流程

安装挂钩一次: pre-commit install （将Ruff、Black和isort添加到每个故事的每个提交中 4.7). 此仓库中还没有TypeScript，因此当TS包出现时，将添加ESLint/Pretier。
每次PR之前 （快速检查表）：

1. pre-commit run --all-files 1. uv run pytest -m "unit or not integration" -q 1. uv run pytest -m integration -q *（要求 CANARY_* 信用）* 1. uv run pytest --cov=canary_mcp --cov-report=term --cov-report=html --cov-report=json:coverage.json 1. python scripts/ci/check_coverage.py coverage.json --baseline-file docs/coverage-baseline.json 1. 打开 htmlcov/index.html 检查更改的模块。

看 docs/开发/测试和覆盖.md 对于扩展的剧本、CI作业矩阵和更新覆盖基线的指导。

添加新的MCP工具

# In src/canary_mcp/server.py

@mcp.tool()
def your_tool_name(parameter: str) -> str:
    """
    Tool description for LLM clients.

    Args:
        parameter: Parameter description

    Returns:
        str: Return value description
    """
    # Implementation
    return "result"

项目状态

所有计划中的史诗都已完成。MCP服务器现在附带：

Canary身份验证、命名空间浏览、标签搜索、元数据和时间序列工具
远程部署操作手册（Windows和Linux）以及容器映像
客户入职指南和健康检查自动化

路线图

✅ 史诗1-故事1.1（当前）

\[x\] 带uv的Python 3.13项目
\[x\] FastMCP SDK集成
\[x\] 带ping工具的基本服务器
\[x\] 测试框架（覆盖率73%）
\[x\] 项目文件

✅ 史诗1-剩余故事

\[x\] 故事1.2：Canary API身份验证和会话管理
\[x\] 故事1.3：list_namespaces工具和验证
\[x\] 故事1.4:搜索标签工具和验证
\[x\] 故事1.5:get_tag_metadata工具和验证
\[x\] 故事1.6：read_timeseries工具和验证
\[x\] 故事1.7:get_server_info工具和验证
\[x\] 故事1.8-1.11：测试、错误处理、安装、开发环境

✅ Epic 2-生产硬化

\[x\] 性能优化（缓存、连接池）
\[x\] 高级错误处理
\[x\] 多站点配置
\[x\] 全面的文件

✅ 史诗3-MVP

\[x\] Epic 3-高级功能（未来）

测试

覆盖

生成最新的覆盖率报告，包括：

uv run pytest --cov=canary_mcp --cov-report=term --cov-report=html --cov-report=json:coverage.json
python scripts/ci/check_coverage.py coverage.json --baseline-file docs/coverage-baseline.json

htmlcov/index.html → 钻取单个文件/行。
scripts/ci/check_coverage.py 强制执行故事 4.7’s政策（回购覆盖率\5，则失败 pp vs docs/coverage-baseline.json).
CI/CD提示：运行上述两个命令并处理脚本的警告输出([coverage] WARNING: overall coverage 73% ...)作为非阻塞信号；只有回归>5 pp触发非零退出代码。

注意：自动覆盖率收集可能需要Python在您的环境中的PATH上可用。如果命令失败（例如在没有Python的Linux Windows子系统上），请安装Python 3.12+或使用项目虚拟环境(.venv/Scripts/python.exe -m pytest ...).

测试类别

单元测试 (tests/unit/)-快速、隔离的组件测试
集成测试 (tests/integration/)-服务器启动和工具调用测试
合同测试 （未来）-API合同验证

贡献

这是一个遵循BMM（BMAD元方法）工作流程开发的黑客马拉松项目。看 docs/ 用于：

PRD.md -产品要求文件
epics.md -史诗和故事分解
stories/ -个人故事实施计划

许可证

看许可证文件。

支持

如有疑问或问题：

API文档 -完整的工具参考，包括错误代码
示例查询库 -20+实际用例
故障排除指南 -常见问题和解决方案
查看测试文件以获取使用示例(tests/integration/)
Canary API文档：https://readapi.canarylabs.com/25.4/

______________________________________________________________________

生成于 克劳德代码 MCP协议： https://modelcontextprotocol.io/

BD Canary MCP

快速接入

详细介绍