Orchestrator/bahn/teamlandkarte-mcp/.github/copilot-instructions.md

Teamlandkarte MCP Server — Copilot Instructions

Project Overview

This is a Python 3.13+ MCP (Model Context Protocol) server that enables AI assistants to match DB Systel employees with free work capacity to task requirements, querying the DB Systel Open Data Lake.

• Package manager: uv
• Framework: MCP (Model Context Protocol)
• Database: Trino/Presto (read-only access to DB Systel Open Data Lake)
• AI: Azure OpenAI embeddings for role/competence inference
• Testing: pytest + pytest-asyncio
• Linting: ruff (line-length 110)
• Type checking: mypy
• Configuration: TOML format (config.toml), credentials via .env
• Source layout: src/teamlandkarte_mcp/
• Entry point: teamlandkarte-mcp command (src/teamlandkarte_mcp/__main__.py)

Commands

• Run server: uv run teamlandkarte-mcp --config config.toml
• Run tests: uv run pytest
• Lint: uv run ruff check src/ tests/
• Format: uv run ruff format src/ tests/
• Type check: uv run mypy src/
• Install deps: uv sync

Project Structure

src/teamlandkarte_mcp/
├── __main__.py          # CLI entry point
├── mcp_server.py        # MCP server + tool definitions
├── config.py            # Configuration management (TOML)
├── models.py            # Data models
├── logging_config.py    # Logging setup
├── azure/               # Azure OpenAI integration (embeddings)
├── database/            # Trino client, schema verification, read-only guard
├── matching/            # Matcher, scorer, similarity engine, BM25+RRF
├── cache/               # Query cache, search cache, embedding cache (SQLite)
└── utils/               # Shared utilities

Architectural Patterns

• Embeddings-only inference: Azure OpenAI text-embedding-3-large (3072 dims) for semantic similarity. No chat/LLM unless use_auto_tagging = true.
• Table-first Markdown output: All MCP tool outputs use Markdown tables.
• Confirmation gate: Hard gate before matching runs (show → ask → confirm).
• Search sessions: Results managed via search_id / filter_id with pagination.
• Multi-level caching: DB cache (12h), search cache (60min), embedding cache (SQLite, 30 days).
• Read-only database: Never write to Trino. Schema verification at startup.

Security Rules

1. Credentials in env vars only — never in config.toml, code, or outputs.
2. Read-only DB — never attempt writes to Trino.
3. Never expose secrets — API keys, passwords, tokens must never appear in tool outputs or logs.
4. .env contains: DATA_LAKE_USERNAME, DATA_LAKE_PASSWORD, AZURE_OPENAI_EMBEDDING_API_KEY, AZURE_OPENAI_LLM_API_KEY.

Code Style

• Line length: 110 characters (ruff configured)
• Type hints everywhere (mypy strict)
• Prefer async/await for I/O operations
• Use dataclasses or Pydantic models for structured data
• Keep functions focused and testable
• Document public APIs with docstrings
• Follow existing patterns in the codebase

OpenSpec Workflow

For significant changes (new capabilities, breaking changes, architecture shifts):

1. Check existing specs: openspec spec list --long
2. Create a proposal in openspec/changes/<change-id>/
3. Validate: openspec validate <change-id> --strict
4. Get approval before implementing

Read openspec/AGENTS.md for full workflow details.