yhteentoimivuusagentti

MCP 服务器

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

概述

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

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

警告

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

支持的平台

安装

先决条件

• 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')"

看 了解详细的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):

{
  "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 到克劳德桌面

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

1. 使用MCPB CLI：

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

安装后，重新启动Claude Desktop。

可用工具

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

术语工具（Sanastot）

数据模型工具（Tietomallit）

代码列表工具（Koodistot）

跨平台工具

示例

搜索术语

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许可证

参考文献

• Sanastot-芬兰术语服务
• Tietomallit-芬兰数据模型服务
• Koodistot-芬兰代码列表服务
• MCP协议文件