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:

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:

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

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

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

References

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