Normatia

🇬🇧 English | 🇪🇸 Español

Normatia

用于西班牙建筑规范合规的开源开发者工具包。

主站：normatia.com API 文档：docs.normatia.com API 基础地址：api.normatia.com

什么是 Normatia？

Normatia 是面向西班牙 AECO 行业（建筑、工程、施工和运营）的建筑规范合规平台。本仓库包含开源开发者工具包：面向 AI 助手的 MCP 服务、TypeScript SDK、API 使用示例，以及可复用的 AI 技能。

MCP 服务

Normatia 提供远程 MCP 服务，让 AI 助手能够访问特定项目的上下文中的西班牙建筑法规——无需安装。

https://mcp.normatia.com/mcp

所有内容均以项目为范围

Normatia 的法规范围按项目确定：normatia.com 上的每个项目都包含其所在市镇、适用法规（国家、自治区、市镇级）、上传的文档、记录的建筑信息以及已保存的计算结果。

这意味着助手无需询问城市、气候区或适用的 CTE 版本——答案会附带已解析的这些信息。而没有项目的市镇也不会有答案：服务会说明这一点，并引导用户创建项目，因为不同市议会的市政条例完全不同。

可用工具

共有 3 个工具，且全部为只读。MCP 接口中的任何操作都不会写入项目。

工具	说明	费用
ask(query, project_id?)	使用自然语言提问，了解适用于某个项目的法规。唯一会返回可引用法规原文的工具。	1 个额度
get_project_info(project_id?)	完整的项目上下文：位置、辖区技术数据、适用法规及其当前版本、文件、生成的文档、记忆和计算结果。	免费
list_projects()	用户可以查询的项目，以及其 project_id、位置和当前激活的项目。	免费

ask 执行的是与 normatia.com 聊天相同的 Agent 循环，而非一次性搜索：它会串联多次搜索、读取项目记忆和已保存的计算结果、查阅上传的文档，并使用经过验证的 [N] 标记引用每个来源。由于调用是同步的，其预算较短——6 轮推理、6 次搜索、120 秒——因此请将客户端的工具调用超时设为 150 秒或更长。

每个工具都接受可选的 project_id，其解析顺序为“显式指定的 project_id → 用户当前激活的项目”。要查询其他市镇，请调用 list_projects() 并传入对应的 id：同一对话中可以查询多个项目，而且用户在网站上当前激活的项目不会因此改变。

设置

Claude

将 Normatia 作为自定义连接器连接到 claude.ai。Free（仅限 1 个连接器）、Pro、Max、Team 和 Enterprise 套餐均可使用。目前处于 Beta 阶段。

Free、Pro 和 Max 套餐：

1. 前往 Customize > Connectors
2. 点击“+”，然后点击“Add custom connector”
3. 输入服务 URL：https://mcp.normatia.com/mcp
4. 选择 OAuth 作为身份验证方式
5. 点击“Add”

Team 和 Enterprise 套餐（所有者）：

1. 前往 Organization settings > Connectors
2. 点击“Add” → 将鼠标悬停在“Custom”上 → 选择“Web”
3. 输入服务 URL：https://mcp.normatia.com/mcp
4. 选择 OAuth 作为身份验证方式
5. 点击“Add”

所有者添加后，成员可前往 Customize > Connectors 进行连接。

配置完成后，在每次对话中点击左下角的“+”按钮 → “Connectors”，即可启用 Normatia。

ChatGPT

将 Normatia 作为自定义 MCP 应用连接到 ChatGPT。Free、Plus、Pro、Business 和 Enterprise/Edu 套餐均可使用。目前处于 Beta 阶段。

1. 启用开发者模式：前往 Settings → Apps → Advanced Settings，然后打开 Developer mode
2. 前往 Settings → Apps → Create
3. 输入服务 URL：https://mcp.normatia.com/mcp
4. 选择 OAuth 作为身份验证方式
5. 点击 Create

创建完成后，在任意对话中点击“+”按钮并选择 Normatia，即可启用该应用。

对于 Business 和 Enterprise/Edu 套餐，工作区管理员必须先从 Workspace Settings → Apps 配置并发布该应用，成员才能使用。

前提条件

以下客户端需要 API 密钥。请在 normatia.com/es/api 获取。密钥格式为 sk-normatia-...。

Claude Desktop

将以下内容添加到配置文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
	"mcpServers": {
		"normatia": {
			"type": "streamable-http",
			"url": "https://mcp.normatia.com/mcp",
			"headers": {
				"Authorization": "Bearer sk-normatia-..."
			}
		}
	}
}

Claude Code

claude mcp add normatia --transport streamable-http https://mcp.normatia.com/mcp \
	-h "Authorization: Bearer sk-normatia-..."

VS Code / GitHub Copilot

将以下内容添加到工作区中的 .vscode/mcp.json：

{
	"servers": {
		"normatia": {
			"type": "streamable-http",
			"url": "https://mcp.normatia.com/mcp",
			"headers": {
				"Authorization": "Bearer sk-normatia-..."
			}
		}
	}
}

也可以将以下内容添加到用户设置（JSON），以便全局使用：

{
	"mcp": {
		"servers": {
			"normatia": {
				"type": "streamable-http",
				"url": "https://mcp.normatia.com/mcp",
				"headers": {
					"Authorization": "Bearer sk-normatia-..."
				}
			}
		}
	}
}

Cursor

将以下内容添加到 Cursor MCP 设置（~/.cursor/mcp.json）：

{
	"mcpServers": {
		"normatia": {
			"type": "streamable-http",
			"url": "https://mcp.normatia.com/mcp",
			"headers": {
				"Authorization": "Bearer sk-normatia-..."
			}
		}
	}
}

Windsurf

将以下内容添加到 Windsurf MCP 设置：

{
	"mcpServers": {
		"normatia": {
			"type": "streamable-http",
			"url": "https://mcp.normatia.com/mcp",
			"headers": {
				"Authorization": "Bearer sk-normatia-..."
			}
		}
	}
}

Zed

将以下内容添加到 Zed 设置（~/.config/zed/settings.json）：

{
	"context_servers": {
		"normatia": {
			"transport": "streamable-http",
			"url": "https://mcp.normatia.com/mcp",
			"headers": {
				"Authorization": "Bearer sk-normatia-..."
			}
		}
	}
}

任意 MCP 客户端

在任何兼容 MCP 的客户端中使用以下连接信息：

设置	值
传输方式	streamable-http
URL	https://mcp.normatia.com/mcp
身份验证标头	Authorization: Bearer sk-normatia-...

有关 30 多种 MCP 客户端的完整设置说明，请参阅 docs.normatia.com/mcp。

示例提示词

连接后，可在 AI 助手中试试以下提示词：

• “我的项目中有哪些现行法规？每项法规分别采用哪个版本？”
• “我的项目可以采用的窗户最大 U 值是多少？”
• “请检查附件中的木工进度表，并告诉我其中的数值是否合规”
• “塞维利亚项目的市政条例要求的最小净高是多少？”
• “比较我的马德里项目与毕尔巴鄂项目的无障碍要求”
• “根据我已保存的计算结果，规范对车库通风有什么规定？”

TypeScript SDK

npm install normatia

import { NormatiaClient } from 'normatia';

const client = new NormatiaClient({ apiKey: 'sk-normatia-...' });
const location = await client.getLocation('ES-41091');
console.log(location.tech_data.climate_zone); // "B4"

完整文档请参阅 packages/sdk-typescript/README.md。

示例

目录	描述
examples/curl	所有主要 API 端点的 cURL 示例
examples/python	使用 httpx 的 Python 示例
examples/typescript	使用 SDK 的 TypeScript 示例

AI 技能

skills 目录包含供使用 Normatia 的 AI Agent 重复使用的系统提示词：

• 建筑规范 — 精通西班牙法规（CTE、RITE、LOE）的导航
• 合规性 — 结构化的合规验证工作流
• 位置感知 — 基于地理位置的法规指导

API 概览

端点	方法	描述
/api/v1/location/search	GET	搜索地理位置
/api/v1/location/{geo_id}	GET	获取位置详情和气候数据
/api/v1/codes/search	GET	搜索建筑规范
/api/v1/codes/{slug}	GET	获取规范详情
/api/v1/codes/{slug}/versions	GET	列出规范版本
/api/v1/codes/{slug}/versions/{version}	GET	获取版本详情和章节
/api/v1/projects	GET	列出用户可查询的项目
/api/v1/project/info	GET	获取项目的完整上下文
/api/v2/ask	POST	针对项目进行 Agent 式法规问答
/api/v1/verify	POST	合规性验证

POST /api/v1/ask（旧版单次 RAG 端点）已冻结，并从公共架构中隐藏。现有集成仍可使用，但新集成应使用 /api/v2/ask。

文档

完整的 API 参考和集成指南请参见 docs.normatia.com。

贡献

欢迎贡献。提交问题或拉取请求前，请阅读 CONTRIBUTING.md。

许可证

MIT — 详见 LICENSE。