Yhteentoimivuusalusta MCP Server

An MCP (Model Context Protocol) server that integrates with Finland's Yhteentoimivuusalusta (Interoperability Platform) to assist with design documentation by ensuring proper use of standardized Finnish terminology, data models, and code values.

Overview

This tool helps when writing design documents, technical specifications, or architecture descriptions for Finnish government or building industry projects by:

Suggesting correct standardized terms from relevant vocabularies
Referencing appropriate data models for data structure descriptions
Providing valid code list values for enumerations
Validating terminology consistency across documentation

Warning

This program is coded, poorly, by someone who has absolutely no idea what they are doing. The code is also heavily AI assisted. Use at your own risk and if possible, via Docker.

Supported Platforms

| Platform | URL | Content | |----------|-----|---------| | Sanastot | sanastot.suomi.fi | ~90 terminologies and vocabularies | | Tietomallit | tietomallit.suomi.fi | ~170 data models and schemas | | Koodistot | koodistot.suomi.fi | 700+ code lists and classifications |

Installation

Prerequisites

Python 3.11 or higher
pip or uv package manager
Docker (optional, recommended for sandboxed execution)

Option 1: Docker (Recommended)

Docker provides sandboxed execution with minimal attack surface:

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

See docs/DOCKER.md for detailed Docker setup instructions.

Option 2: Install from source

# 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 .

Optional dependencies

# For improved fuzzy matching
pip install rapidfuzz

# For Finnish NLP (lemmatization)
pip install voikko

Configuration

Copy the example configuration file and adjust as needed:

cp config.yaml.example config.yaml

Configuration options

# 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

Usage

Running the server

python -m yhteentoimivuusalusta_mcp.server

Claude Desktop Integration

Option 1: Automatic Setup (Recommended)

Run the setup script to automatically configure Claude Desktop:

python scripts/setup_claude_desktop.py

This will detect your OS, find the correct config location, and add the MCP server configuration.

To preview without writing: ``bash python scripts/setup_claude_desktop.py --print-only ``

Option 2: Manual Configuration

Add to your Claude Desktop configuration (claude_desktop_config.json):

| OS | Config Location | |----|-----------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %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"
    }
  }
}

Option 3: Docker (Sandboxed)

For enhanced security, run the MCP server in a Docker container:

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

This provides:

Isolated filesystem (no access to host files)
Memory and CPU limits
Non-root execution
Persistent cache via Docker volume

Option 4: Install as Desktop Extension (MCPB)

This project includes a manifest.json (v0.3) for MCPB desktop extensions:

# Create the bundled extension
python scripts/create_bundle.py

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

To install the extension:

Bundled (.mcpb): Double-click or drag build/yhteentoimivuusalusta-0.1.0.mcpb to Claude Desktop

Unpacked (development): In Claude Desktop settings, add the extension pointing to build/unpacked/ directory

Using MCPB CLI:

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

After installation, restart Claude Desktop.

Available Tools

The server provides 13 MCP tools across three categories:

Terminology Tools (Sanastot)

| Tool | Description | |------|-------------| | search_terminology | Search for terms across vocabularies with fuzzy matching | | get_concept_details | Get detailed information about a specific concept | | list_vocabularies | List all available vocabularies |

Data Model Tools (Tietomallit)

| Tool | Description | |------|-------------| | search_datamodel | Search for data models by name or description | | get_datamodel_classes | Get all classes from a specific data model | | get_model_vocabulary_links | Find vocabularies linked to a data model |

Code List Tools (Koodistot)

| Tool | Description | |------|-------------| | search_codelist | Search for code lists by name or description | | get_codes | Get all codes from a specific code list | | export_codes_csv | Export codes to CSV format |

Cross-Platform Tools

| Tool | Description | |------|-------------| | validate_terminology | Validate text against standardized vocabularies | | unified_search | Search all three platforms simultaneously | | suggest_references | Analyze text and suggest relevant standards to reference | | get_codelist_for_attribute | Find appropriate code lists for data model attributes |

Examples

Search for a term

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

Validate terminology in a document

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

Unified search across all platforms

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

Suggest standards for documentation

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

Common Resource IDs

Vocabularies (Sanastot)

rakymp - Built environment vocabulary (Rakennetun ympäristön sanasto)
jhka - Public administration architecture (Julkisen hallinnon kokonaisarkkitehtuuri)
oksa - Education vocabulary (Opetus- ja koulutussanasto)
kela - Social security vocabulary (Kelan sanasto)

Data Models (Tietomallit)

rytj-kaava - Spatial planning data model
raktkk - Physical building data model
digione - Education data models

Code Registries (Koodistot)

rakennustieto - Building information codes
koulutus - Education codes
julkishallinto - Public administration codes

Features

Caching

Persistent disk cache with configurable TTL
Automatic cache invalidation
Offline mode support with stale cache fallback

Performance

Rate limiting (token bucket algorithm, 10 req/sec default)
Parallel API requests where possible
Response caching to minimize API calls

Reliability

Automatic retry with exponential backoff
Graceful degradation when APIs are unavailable
Offline mode returns cached data when network fails

Project Structure

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

Development

Running tests

pytest tests/

Code formatting

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

License

MIT License

Yhteentoimivuusalusta MCP Server