ankn
a5f8fb49ab
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# 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.
|