AI导哈

芬兰互操作性平台MCP服务器

一个与芬兰互操作性平台集成的MCP服务器，通过确保使用标准化芬兰术语、数据模型和代码值来帮助设计文档编写。

  • by jrastas
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 jrastas/yhteentoimivuusagentti

使用说明

MCP 服务器

MCP（模型上下文协议）服务器，与芬兰的Yhteentoimivuusalusta（互操作性平台）集成，通过确保正确使用标准化的芬兰术语、数据模型和代码值来协助设计文档。

概述

该工具有助于为芬兰政府或建筑行业项目编写设计文档、技术规范或架构描述，方法如下：

  • 从相关词汇中提出正确的标准化术语
  • 参考适当的数据模型进行数据结构描述
  • 为枚举提供有效的代码列表值
  • 验证文档中术语的一致性

警告

这个程序是由一个完全不知道自己在做什么的人编写的，很糟糕。该代码在很大程度上也是人工智能辅助的。使用风险自负，如果可能的话，通过Docker。

支持的平台

平台 URL 内容
单词 sanastot.suomi.fi ~90个术语和词汇
数据模型 tietomallit.uomi.fi 约170个数据模型和模式
编码 koodistot.somi.fi 700+代码列表和分类

安装

先决条件

  • Python 3.11或更高版本
  • pip或uv包管理器
  • Docker（可选，建议用于沙盒执行）

选项1:Docker（推荐）

Docker以最小的攻击面提供沙盒执行：

# Clone and build
git clone https://github.com/yaskael/yhteentoimivuusagentti.git
cd yhteentoimivuusagentti
docker build -t yhteentoimivuusalusta-mcp:latest .

# Test the build
docker run --rm yhteentoimivuusalusta-mcp:latest python -c "import yhteentoimivuusalusta_mcp.server; print('OK')"

看 docs/DOCKER.md 了解详细的Docker设置说明。

选项2：从源代码安装

# Clone the repository
git clone https://github.com/yaskael/yhteentoimivuusagentti.git
cd yhteentoimivuusagentti

# Install in development mode
pip install -e .

# Or with uv
uv pip install -e .

可选依赖

# For improved fuzzy matching
pip install rapidfuzz

# For Finnish NLP (lemmatization)
pip install voikko

配置

复制示例配置文件并根据需要进行调整：

cp config.yaml.example config.yaml

配置选项

# config.yaml
cache:
  enabled: true
  directory: ~/.cache/yhteentoimivuusalusta

rate_limit:
  requests_per_second: 10.0

# API endpoints (defaults shown)
apis:
  sanastot:
    base_url: https://sanastot.suomi.fi/terminology-api
  tietomallit:
    base_url: https://tietomallit.suomi.fi/datamodel-api
  koodistot:
    base_url: https://koodistot.suomi.fi/codelist-api/api/v1

用法

运行服务器

python -m yhteentoimivuusalusta_mcp.server

Claude桌面集成

选项1：自动设置（推荐）

运行安装脚本以自动配置Claude Desktop：

python scripts/setup_claude_desktop.py

这将检测您的操作系统，找到正确的配置位置，并添加MCP服务器配置。

要预览而不书写，请执行以下操作：

python scripts/setup_claude_desktop.py --print-only

选项2：手动配置

添加到您的Claude Desktop配置(claude_desktop_config.json):

操作系统 配置位置
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
窗户 %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "yhteentoimivuusalusta": {
      "command": "python",
      "args": ["-m", "yhteentoimivuusalusta_mcp.server"],
      "cwd": "/path/to/yhteentoimivuusagentti"
    }
  }
}

选项3:Docker（沙盒）

为了增强安全性，请在Docker容器中运行MCP服务器：

{
  "mcpServers": {
    "yhteentoimivuusalusta": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--memory=512m", "--cpus=1.0",
        "-v", "yhteentoimivuusalusta-cache:/app/cache",
        "yhteentoimivuusalusta-mcp:latest"
      ]
    }
  }
}

这提供了：

  • 独立文件系统（无法访问主机文件）
  • 内存和CPU限制
  • 非根执行
  • 通过Docker卷实现持久缓存

选项4：作为桌面扩展安装（MCPB）

该项目包括 manifest.json （v0.3）适用于MCPB桌面扩展：

# Create the bundled extension
python scripts/create_bundle.py

# This creates:
# - build/yhteentoimivuusalusta-0.1.0.mcpb (bundled)
# - build/unpacked/ (for unpacked installation)

要安装扩展，请执行以下操作：

  1. 捆绑（.mcpb）： 双击或拖动 build/yhteentoimivuusalusta-0.1.0.mcpb 到克劳德桌面

  2. 未打包（开发）： 在Claude Desktop设置中，添加指向的扩展名 build/unpacked/ 目录

  3. 使用MCPB CLI：

    npm install -g @anthropic-ai/mcpb
mcpb install ./build/yhteentoimivuusalusta-0.1.0.mcpb

安装后，重新启动Claude Desktop。

可用工具

该服务器提供13个MCP工具，分为三类：

术语工具（Sanastot）

工具 说明
search_terminology 使用模糊匹配在词汇表中搜索术语
get_concept_details 获取特定概念的详细信息
list_vocabularies 列出所有可用词汇

数据模型工具（Tietomallit）

工具 说明
search_datamodel 按名称或描述搜索数据模型
get_datamodel_classes 从特定数据模型中获取所有类
get_model_vocabulary_links 查找与数据模型链接的词汇表

代码列表工具（Koodistot）

工具 说明
search_codelist 按名称或描述搜索代码列表
get_codes 从特定代码列表中获取所有代码
export_codes_csv 将代码导出为CSV格式

跨平台工具

工具 说明
validate_terminology 根据标准化词汇表验证文本
unified_search 同时搜索所有三个平台
suggest_references 分析文本并提出相关标准以供参考
get_codelist_for_attribute 查找数据模型属性的适当代码列表

示例

搜索术语

Tool: search_terminology
Arguments: { "query": "rakennus", "vocabulary_id": "rakymp" }

验证文档中的术语

Tool: validate_terminology
Arguments: {
  "text": "Rakennuksen kerrosala lasketaan ulkoseinien ulkopintojen mukaan.",
  "vocabulary_ids": ["rakymp"]
}

跨所有平台的统一搜索

Tool: unified_search
Arguments: {
  "query": "kaava",
  "platforms": ["sanastot", "tietomallit", "koodistot"],
  "limit": 5
}

建议文件编制标准

Tool: suggest_references
Arguments: {
  "text": "Järjestelmä käsittelee rakennuslupahakemuksia ja niiden liitteitä.",
  "include_vocabularies": true,
  "include_datamodels": true,
  "include_codelists": true
}

通用资源ID

词汇（Sanastot）

  • rakymp 建筑环境词汇（Built Environment Vocabulary）
  • jhka 公共管理架构（Public Administration Architecture）
  • oksa 教育词汇（Education Vocabulary）
  • kela -社会保障词汇（Kelan sanasto）

数据模型（Data Models）

  • rytj-kaava -空间规划数据模型
  • raktkk -物理建筑数据模型
  • digione -教育数据模型

代码注册表（Koodistot）

  • rakennustieto -建筑信息规范
  • koulutus -教育代码
  • julkishallinto -公共行政法规

特性

缓存

  • 具有可配置TTL的持久磁盘缓存
  • 自动缓存失效
  • 支持离线模式，支持过时缓存回退

演出

  • 速率限制（令牌桶算法，默认10请求/秒）
  • 尽可能并行API请求
  • 响应缓存可最大限度地减少API调用

可靠性

  • 指数回退自动重试
  • API不可用时性能下降
  • 离线模式在网络故障时返回缓存数据

项目结构

yhteentoimivuusalusta-mcp/
├── src/
│   └── yhteentoimivuusalusta_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP server entry point
│       ├── tools/
│       │   ├── terminology.py     # Sanastot tools
│       │   ├── datamodel.py       # Tietomallit tools
│       │   ├── codelist.py        # Koodistot tools
│       │   ├── validation.py      # Text validation
│       │   └── unified.py         # Cross-platform tools
│       ├── clients/
│       │   ├── base.py            # Base HTTP client
│       │   ├── sanastot.py        # Sanastot API client
│       │   ├── tietomallit.py     # Tietomallit API client
│       │   └── koodistot.py       # Koodistot API client
│       ├── models/
│       │   └── schemas.py         # Pydantic models
│       └── utils/
│           ├── cache.py           # Caching utilities
│           ├── config.py          # Configuration loader
│           └── fuzzy.py           # Fuzzy matching
├── docs/
│   └── DOCKER.md                  # Docker setup guide
├── tests/
├── Dockerfile                     # Docker build configuration
├── docker-compose.yml             # Docker Compose configuration
├── pyproject.toml
└── config.yaml.example

发展

运行测试

pytest tests/

代码格式化

ruff format src/ tests/
ruff check src/ tests/

许可证

MIT许可证

参考文献

相关 MCP