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

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:

python scripts/setup_claude_desktop.py --print-only

Option 2: Manual Configuration

Add to your Claude Desktop configuration (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:

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

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

1. 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)

Data Model Tools (Tietomallit)

Code List Tools (Koodistot)

Cross-Platform Tools

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

References

• Sanastot - Finnish Terminology Service
• Tietomallit - Finnish Data Model Service
• Koodistot - Finnish Code List Service
• MCP Protocol Documentation