Migrate all repos into monorepo context folders
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.
This commit is contained in:
@@ -0,0 +1 @@
|
||||
{"specId": "036a2f60-80b4-4a0b-8cac-7201dd154bed", "workflowType": "requirements-first", "specType": "feature"}
|
||||
@@ -0,0 +1,163 @@
|
||||
# Design Document: Capacity Details Enrichment
|
||||
|
||||
## Overview
|
||||
|
||||
This feature enriches the existing `get_capacity_details` MCP tool to display additional information about a capacity: its description, references (partner + projects), and certifications. The data is already available in the database and exposed through existing `DBClient` methods (`get_capacity_description`, `get_capacity_references`, `get_capacity_certificates`). The change is purely in the tool's output formatting layer.
|
||||
|
||||
The tool currently returns a Markdown table with basic capacity fields (ID, Owner, Role, Competences, Availability) followed by a "Next steps" section. After this enhancement, it will include three additional sections between the table and the next steps: Beschreibung, Referenzen, and Zertifizierungen.
|
||||
|
||||
## Architecture
|
||||
|
||||
The change is localized to the `get_capacity_details` tool function inside `build_server()` in `src/teamlandkarte_mcp/mcp_server.py`. No new modules, classes, or external dependencies are needed.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as MCP Client
|
||||
participant Tool as get_capacity_details
|
||||
participant DB as DBClient
|
||||
|
||||
Client->>Tool: call(capacity_id)
|
||||
Tool->>DB: get_capacity_by_id(capacity_id)
|
||||
DB-->>Tool: Capacity | None
|
||||
Tool->>DB: get_capacity_description(capacity_id)
|
||||
DB-->>Tool: str | None
|
||||
Tool->>DB: get_capacity_references(capacity_id)
|
||||
DB-->>Tool: list[CapacityReferenceRow]
|
||||
Tool->>DB: get_capacity_certificates(capacity_id)
|
||||
DB-->>Tool: list[str]
|
||||
Tool-->>Client: Formatted Markdown string
|
||||
```
|
||||
|
||||
### Design Decisions
|
||||
|
||||
1. **Sequential DB calls** – The three additional queries are simple key lookups on indexed views. Parallelizing them would add complexity (async conversion of the tool) for negligible latency gain. Keep the tool synchronous.
|
||||
2. **Formatting inline** – The formatting logic is simple string concatenation. No need for a separate formatter class.
|
||||
3. **Empty-state handling** – Each section shows a "(keine)" placeholder when data is absent, keeping the output structure predictable for LLM consumers.
|
||||
|
||||
## Components and Interfaces
|
||||
|
||||
### Modified Component: `get_capacity_details` tool
|
||||
|
||||
**Current signature** (unchanged):
|
||||
```python
|
||||
def get_capacity_details(capacity_id: int | str) -> str:
|
||||
```
|
||||
|
||||
**New internal calls added:**
|
||||
```python
|
||||
description: str | None = db_client.get_capacity_description(capacity_id)
|
||||
references: list[CapacityReferenceRow] = db_client.get_capacity_references(capacity_id)
|
||||
certificates: list[str] = db_client.get_capacity_certificates(capacity_id)
|
||||
```
|
||||
|
||||
**Output format** (Markdown string):
|
||||
```
|
||||
| ID | Owner | Role | Competences | Availability |
|
||||
| ... |
|
||||
|
||||
## Beschreibung
|
||||
|
||||
<description text or "(keine)">
|
||||
|
||||
## Referenzen
|
||||
|
||||
- **Partner A**: Projekt X, Projekt Y
|
||||
- Projekt Z (no partner)
|
||||
|
||||
*or* Referenzen: (keine)
|
||||
|
||||
## Zertifizierungen
|
||||
|
||||
- Zertifikat 1
|
||||
- Zertifikat 2
|
||||
|
||||
*or* Zertifizierungen: (keine)
|
||||
|
||||
## Next steps
|
||||
|
||||
Call find_matching_tasks(capacity_id=...) to see matching open tasks.
|
||||
```
|
||||
|
||||
### Existing Interfaces Used (no changes)
|
||||
|
||||
| Method | Returns | Source |
|
||||
|--------|---------|--------|
|
||||
| `DBClient.get_capacity_description(capacity_id)` | `str \| None` | `teamlandkarte_v_capacities_latest.description` |
|
||||
| `DBClient.get_capacity_references(capacity_id)` | `list[CapacityReferenceRow]` | `teamlandkarte_v_capacity_references_latest` joined with partners |
|
||||
| `DBClient.get_capacity_certificates(capacity_id)` | `list[str]` | `teamlandkarte_v_capacity_certificates_latest.description` |
|
||||
|
||||
## Data Models
|
||||
|
||||
### CapacityReferenceRow (existing, unchanged)
|
||||
|
||||
```python
|
||||
class CapacityReferenceRow(TypedDict):
|
||||
partner_name: str # May be empty string when partner_id is NULL
|
||||
projects: str # Project text from the references view
|
||||
```
|
||||
|
||||
No new data models are introduced.
|
||||
|
||||
|
||||
## Correctness Properties
|
||||
|
||||
*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
||||
|
||||
### Property 1: All enrichment data is fetched for any capacity
|
||||
|
||||
*For any* valid capacity ID that resolves to an existing capacity, the tool SHALL invoke `get_capacity_description`, `get_capacity_references`, and `get_capacity_certificates` with that capacity ID.
|
||||
|
||||
**Validates: Requirements 1.1, 2.1, 3.1**
|
||||
|
||||
### Property 2: Non-empty data appears in output
|
||||
|
||||
*For any* capacity with a non-empty description, a non-empty list of references, and a non-empty list of certificates, the formatted output SHALL contain the description text, every reference's projects text, and every certificate string.
|
||||
|
||||
**Validates: Requirements 1.2, 2.2, 3.2**
|
||||
|
||||
### Property 3: Section ordering is fixed
|
||||
|
||||
*For any* capacity (regardless of which fields are empty or populated), the output string SHALL contain the section markers in the order: capacity table first, then "Beschreibung", then "Referenzen", then "Zertifizierungen", then "Next steps" — and each section SHALL be separated by at least one blank line.
|
||||
|
||||
**Validates: Requirements 4.1, 4.2**
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Behaviour |
|
||||
|----------|-----------|
|
||||
| `get_capacity_by_id` returns `None` | Return `"Capacity not found: {capacity_id}"` (existing behaviour, unchanged) |
|
||||
| `get_capacity_description` returns `None` | Display `"Beschreibung: (keine)"` |
|
||||
| `get_capacity_references` returns `[]` | Display `"Referenzen: (keine)"` |
|
||||
| `get_capacity_certificates` returns `[]` | Display `"Zertifizierungen: (keine)"` |
|
||||
| `get_capacity_references` returns a row with empty `partner_name` | Display only the `projects` text (no bold partner prefix) |
|
||||
| Any DB call raises an exception | Let it propagate (existing error handling in the MCP framework catches and reports it) |
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Test `get_capacity_details` with a mock DB client returning known data for all three new fields → verify output contains expected sections and content.
|
||||
- Test empty-state: description=None, references=[], certificates=[] → verify "(keine)" placeholders appear.
|
||||
- Test edge case: reference with empty `partner_name` → verify only projects text is shown.
|
||||
- Test that capacity-not-found still returns the error message unchanged.
|
||||
|
||||
### Property-Based Tests
|
||||
|
||||
Library: **Hypothesis** (Python)
|
||||
|
||||
Each property test runs a minimum of 100 iterations.
|
||||
|
||||
- **Property 1 test**: Generate random capacity IDs and mock DB responses. Verify all three DB methods are called with the correct ID.
|
||||
- Tag: `Feature: capacity-details-enrichment, Property 1: All enrichment data is fetched for any capacity`
|
||||
|
||||
- **Property 2 test**: Generate random non-empty descriptions (text strategy), random lists of `CapacityReferenceRow` dicts with non-empty `projects` and `partner_name`, and random lists of non-empty certificate strings. Call the formatting logic and assert all generated data appears in the output.
|
||||
- Tag: `Feature: capacity-details-enrichment, Property 2: Non-empty data appears in output`
|
||||
|
||||
- **Property 3 test**: Generate random combinations of present/absent data (description: str|None, references: list of 0-5 items, certificates: list of 0-5 items). Call the formatting logic and assert section headers appear in the correct order with blank-line separation.
|
||||
- Tag: `Feature: capacity-details-enrichment, Property 3: Section ordering is fixed`
|
||||
|
||||
### Test Configuration
|
||||
|
||||
- Property-based testing library: `hypothesis` (already available in the project's test dependencies)
|
||||
- Minimum iterations: 100 per property (`@settings(max_examples=100)`)
|
||||
- Each test tagged with a comment referencing the design property
|
||||
@@ -0,0 +1,57 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
Das MCP-Tool `get_capacity_details` zeigt aktuell nur eine Tabelle mit ID, Owner, Rolle, Kompetenzen und Verfügbarkeit an. Es fehlen die Beschreibung (Description), Referenzen und Zertifizierungen einer Kapazität. Diese Informationen sind bereits in der Datenbank vorhanden und über die DB-Client-Methoden `get_capacity_description`, `get_capacity_references` und `get_capacity_certificates` abrufbar. Das Tool soll erweitert werden, um diese zusätzlichen Felder anzuzeigen.
|
||||
|
||||
## Glossary
|
||||
|
||||
- **MCP_Server**: Der Teamlandkarte MCP Server, der Tools für Kapazitäts- und Aufgabenabgleich bereitstellt
|
||||
- **get_capacity_details_Tool**: Das MCP-Tool, das Detailinformationen zu einer einzelnen Kapazität anzeigt
|
||||
- **DB_Client**: Die Datenbankzugriffsschicht, die Kapazitätsdaten aus der Trino-Datenbank liest
|
||||
- **Capacity**: Ein Eintrag, der die verfügbare Kapazität einer Person beschreibt (ID, Owner, Rolle, Kompetenzen, Verfügbarkeit)
|
||||
- **Description**: Freitext-Beschreibung einer Kapazität aus `teamlandkarte_v_capacities_latest.description`
|
||||
- **Reference**: Ein Referenzeintrag bestehend aus Partnername und Projekten aus `teamlandkarte_v_capacity_references_latest`
|
||||
- **Certificate**: Eine Zertifizierungsbeschreibung aus `teamlandkarte_v_capacity_certificates_latest`
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1: Beschreibung anzeigen
|
||||
|
||||
**User Story:** Als Nutzer möchte ich die Beschreibung einer Kapazität im Tool `get_capacity_details` sehen, damit ich ein vollständigeres Bild der Kapazität erhalte.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a capacity is retrieved by `get_capacity_details`, THE get_capacity_details_Tool SHALL fetch the description via `DB_Client.get_capacity_description`
|
||||
2. WHEN the description is non-empty, THE get_capacity_details_Tool SHALL display the description in a dedicated section labeled "Beschreibung" below the capacity table
|
||||
3. WHEN the description is empty or not available, THE get_capacity_details_Tool SHALL display "Beschreibung: (keine)" in the description section
|
||||
|
||||
### Requirement 2: Referenzen anzeigen
|
||||
|
||||
**User Story:** Als Nutzer möchte ich die Referenzen einer Kapazität im Tool `get_capacity_details` sehen, damit ich die bisherigen Projekterfahrungen der Person einschätzen kann.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a capacity is retrieved by `get_capacity_details`, THE get_capacity_details_Tool SHALL fetch the references via `DB_Client.get_capacity_references`
|
||||
2. WHEN references exist, THE get_capacity_details_Tool SHALL display each reference as a bullet point in a section labeled "Referenzen", including partner name and projects
|
||||
3. WHEN a reference has an empty partner name, THE get_capacity_details_Tool SHALL display only the projects for that reference entry
|
||||
4. WHEN no references exist, THE get_capacity_details_Tool SHALL display "Referenzen: (keine)"
|
||||
|
||||
### Requirement 3: Zertifizierungen anzeigen
|
||||
|
||||
**User Story:** Als Nutzer möchte ich die Zertifizierungen einer Kapazität im Tool `get_capacity_details` sehen, damit ich die formalen Qualifikationen der Person erkennen kann.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a capacity is retrieved by `get_capacity_details`, THE get_capacity_details_Tool SHALL fetch the certificates via `DB_Client.get_capacity_certificates`
|
||||
2. WHEN certificates exist, THE get_capacity_details_Tool SHALL display each certificate as a bullet point in a section labeled "Zertifizierungen"
|
||||
3. WHEN no certificates exist, THE get_capacity_details_Tool SHALL display "Zertifizierungen: (keine)"
|
||||
|
||||
### Requirement 4: Darstellungsreihenfolge
|
||||
|
||||
**User Story:** Als Nutzer möchte ich eine konsistente und übersichtliche Darstellung aller Kapazitätsdetails, damit ich die Informationen schnell erfassen kann.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE get_capacity_details_Tool SHALL display sections in the following fixed order: Capacity-Tabelle, Beschreibung, Referenzen, Zertifizierungen, Next Steps
|
||||
2. THE get_capacity_details_Tool SHALL separate each section with a blank line for Lesbarkeit
|
||||
@@ -0,0 +1,86 @@
|
||||
# Implementation Plan: Capacity Details Enrichment
|
||||
|
||||
## Overview
|
||||
|
||||
Extend the `get_capacity_details` tool in `src/teamlandkarte_mcp/mcp_server.py` to fetch and display description, references, and certificates for a capacity. The change is localized to the tool function with inline formatting. All DB client methods already exist.
|
||||
|
||||
## Tasks
|
||||
|
||||
- [x] 1. Extend `get_capacity_details` with enrichment data fetching and formatting
|
||||
- [x] 1.1 Add DB calls for description, references, and certificates
|
||||
- After the existing `get_capacity_by_id` call, add sequential calls to `db_client.get_capacity_description(capacity_id)`, `db_client.get_capacity_references(capacity_id)`, and `db_client.get_capacity_certificates(capacity_id)`
|
||||
- _Requirements: 1.1, 2.1, 3.1_
|
||||
|
||||
- [x] 1.2 Format the Beschreibung section
|
||||
- If description is non-empty, render `## Beschreibung\n\n<text>`
|
||||
- If description is None or empty, render `## Beschreibung\n\nBeschreibung: (keine)`
|
||||
- _Requirements: 1.2, 1.3_
|
||||
|
||||
- [x] 1.3 Format the Referenzen section
|
||||
- If references exist, render `## Referenzen` followed by bullet points: `- **partner_name**: projects` for each reference
|
||||
- If a reference has an empty `partner_name`, render only `- projects` (no bold partner prefix)
|
||||
- If no references exist, render `## Referenzen\n\nReferenzen: (keine)`
|
||||
- _Requirements: 2.2, 2.3, 2.4_
|
||||
|
||||
- [x] 1.4 Format the Zertifizierungen section
|
||||
- If certificates exist, render `## Zertifizierungen` followed by bullet points: `- certificate` for each entry
|
||||
- If no certificates exist, render `## Zertifizierungen\n\nZertifizierungen: (keine)`
|
||||
- _Requirements: 3.2, 3.3_
|
||||
|
||||
- [x] 1.5 Assemble output in fixed section order
|
||||
- Combine sections in order: capacity table, Beschreibung, Referenzen, Zertifizierungen, Next Steps
|
||||
- Separate each section with a blank line
|
||||
- _Requirements: 4.1, 4.2_
|
||||
|
||||
- [x] 2. Write unit tests for the enriched output
|
||||
- [x] 2.1 Test full data scenario
|
||||
- Mock DB client to return a known description, list of references (with and without partner_name), and list of certificates
|
||||
- Assert output contains all expected section headers, content, and correct ordering
|
||||
- Create test file `tests/test_capacity_details_enrichment.py`
|
||||
- _Requirements: 1.2, 2.2, 2.3, 3.2, 4.1_
|
||||
|
||||
- [x] 2.2 Test empty-state scenario
|
||||
- Mock DB client to return None description, empty references list, empty certificates list
|
||||
- Assert output contains "(keine)" placeholders for all three sections
|
||||
- _Requirements: 1.3, 2.4, 3.3_
|
||||
|
||||
- [x] 2.3 Test capacity-not-found unchanged
|
||||
- Mock `get_capacity_by_id` to return None
|
||||
- Assert the tool still returns the existing error message without calling enrichment methods
|
||||
- _Requirements: (error handling, no regression)_
|
||||
|
||||
- [x] 3. Checkpoint
|
||||
- Ensure all tests pass, ask the user if questions arise.
|
||||
|
||||
- [x] 4. Property-based tests with Hypothesis
|
||||
- [x] 4.1 Write property test: All enrichment data is fetched
|
||||
- **Property 1: All enrichment data is fetched for any capacity**
|
||||
- Generate random capacity IDs; mock DB to return a capacity. Verify `get_capacity_description`, `get_capacity_references`, and `get_capacity_certificates` are each called exactly once with the correct ID.
|
||||
- Create test file `tests/test_capacity_details_enrichment_pbt.py`
|
||||
- **Validates: Requirements 1.1, 2.1, 3.1**
|
||||
|
||||
- [x] 4.2 Write property test: Non-empty data appears in output
|
||||
- **Property 2: Non-empty data appears in output**
|
||||
- Generate random non-empty descriptions (text strategy), random lists of `CapacityReferenceRow` dicts with non-empty `projects` and `partner_name`, and random lists of non-empty certificate strings. Assert all generated data appears in the formatted output.
|
||||
- **Validates: Requirements 1.2, 2.2, 3.2**
|
||||
|
||||
- [x] 4.3 Write property test: Section ordering is fixed
|
||||
- **Property 3: Section ordering is fixed**
|
||||
- Generate random combinations of present/absent data (description: str|None, references: 0-5 items, certificates: 0-5 items). Assert section headers appear in the correct order with blank-line separation.
|
||||
- **Validates: Requirements 4.1, 4.2**
|
||||
|
||||
- [x] 5. Final checkpoint
|
||||
- Ensure all tests pass, ask the user if questions arise.
|
||||
|
||||
- [x] 6. Update agent skill documentation
|
||||
- [x] 6.1 Update `.github/skills/capacity-browsing/SKILL.md`
|
||||
- Change the `get_capacity_details` description to mention description, references, and certifications alongside role, competences, and availability window
|
||||
- [x] 6.2 Update `.kiro/agents/teamlandkarte.md`
|
||||
- Change the `get_capacity_details` description to mention that it shows description, references, and certifications alongside the basic profile
|
||||
|
||||
## Notes
|
||||
|
||||
- Tasks marked with `*` are optional and can be skipped for faster MVP
|
||||
- The implementation language is Python (matching the existing codebase and design)
|
||||
- All DB client methods (`get_capacity_description`, `get_capacity_references`, `get_capacity_certificates`) already exist — no data layer changes needed
|
||||
- Property tests use Hypothesis with `@settings(max_examples=100)`
|
||||
Reference in New Issue
Block a user