@redaksjon/protokoll 1.0.2 → 1.0.8

package/docs/MCP_RESOURCES.md

@@ -0,0 +1,301 @@
+# Protokoll MCP Resources
+
+Protokoll exposes several types of resources through its MCP server, providing AI assistants with read-only access to transcripts, audio files, context entities, and configuration.
+
+## Resource Types
+
+### 1. Audio Resources
+
+#### Inbound Audio Files
+**URI Template**: `protokoll://audio/inbound?directory={directory}`
+
+Lists audio files waiting to be processed in the input directory.
+
+**Response Format**:
+```json
+{
+  "directory": "/absolute/path/to/recordings",
+  "count": 5,
+  "totalSize": 52428800,
+  "files": [
+    {
+      "filename": "recording-2026-01-29.m4a",
+      "path": "/absolute/path/to/recordings/recording-2026-01-29.m4a",
+      "size": 10485760,
+      "sizeHuman": "10.00 MB",
+      "modified": "2026-01-29T20:15:30.000Z",
+      "extension": "m4a"
+    }
+  ],
+  "supportedExtensions": ["mp3", "mp4", "mpeg", "mpga", "m4a", "wav", "webm", "qta"]
+}
+```
+
+**Use Cases**:
+- Check if there are audio files ready to process
+- Determine which files to transcribe next
+- Monitor the inbound queue
+
+#### Processed Audio Files
+**URI Template**: `protokoll://audio/processed?directory={directory}`
+
+Lists audio files that have been processed and moved to the processed directory.
+
+**Response Format**: Same as inbound audio files
+
+**Use Cases**:
+- Track processing history
+- Verify files were successfully processed
+- Clean up old processed files
+
+### 2. Transcript Resources
+
+#### Individual Transcript
+**URI Template**: `protokoll://transcript/{path}`
+
+Reads a specific transcript file.
+
+**Response Format**: Raw markdown content of the transcript
+
+**Use Cases**:
+- Review transcript content
+- Extract information from transcripts
+- Analyze transcript metadata
+
+#### Transcripts List
+**URI Template**: `protokoll://transcripts?directory={directory}&startDate={date}&endDate={date}&limit={n}&offset={n}`
+
+Lists transcripts in a directory with filtering and pagination.
+
+**Query Parameters**:
+- `directory` (required): Directory to search for transcripts
+- `startDate` (optional): Filter transcripts from this date onwards (YYYY-MM-DD)
+- `endDate` (optional): Filter transcripts up to this date (YYYY-MM-DD)
+- `limit` (optional): Maximum number of results (default: 50)
+- `offset` (optional): Number of results to skip (default: 0)
+
+**Response Format**:
+```json
+{
+  "directory": "/path/to/transcripts",
+  "transcripts": [
+    {
+      "uri": "protokoll://transcript/path/to/file.md",
+      "path": "/absolute/path/to/file.md",
+      "filename": "2026-01-29-1015-meeting-notes.md",
+      "date": "2026-01-29",
+      "time": "10:15",
+      "title": "Meeting Notes"
+    }
+  ],
+  "pagination": {
+    "total": 100,
+    "limit": 50,
+    "offset": 0,
+    "hasMore": true
+  },
+  "filters": {
+    "startDate": "2026-01-01",
+    "endDate": "2026-01-31"
+  }
+}
+```
+
+**Use Cases**:
+- Browse recent transcripts
+- Search for transcripts by date range
+- Paginate through large transcript collections
+
+### 3. Context Entity Resources
+
+#### Individual Entity
+**URI Template**: `protokoll://entity/{type}/{id}`
+
+Reads a specific context entity (person, project, term, company, or ignored term).
+
+**Entity Types**:
+- `person`: People mentioned in transcripts
+- `project`: Projects that affect routing and classification
+- `term`: Domain-specific terminology and acronyms
+- `company`: Organizations referenced in notes
+- `ignored`: Terms that are explicitly ignored
+
+**Response Format**: YAML representation of the entity
+
+**Example** (person):
+```yaml
+id: john-smith
+name: John Smith
+type: person
+firstName: John
+lastName: Smith
+company: acme-corp
+role: Engineering Manager
+sounds_like:
+  - jon smith
+  - john smyth
+context: Works on the infrastructure team
+```
+
+**Use Cases**:
+- Look up entity details
+- Check phonetic variants for name correction
+- Review entity relationships
+
+#### Entities List
+**URI Template**: `protokoll://entities/{type}`
+
+Lists all entities of a given type.
+
+**Response Format**:
+```json
+{
+  "entityType": "person",
+  "count": 25,
+  "entities": [
+    {
+      "uri": "protokoll://entity/person/john-smith",
+      "id": "john-smith",
+      "name": "John Smith",
+      "company": "acme-corp",
+      "role": "Engineering Manager"
+    }
+  ]
+}
+```
+
+**Use Cases**:
+- Browse all people, projects, terms, or companies
+- Build entity indexes
+- Discover available context
+
+### 4. Configuration Resource
+
+**URI Template**: `protokoll://config` or `protokoll://config/{path}`
+
+Provides information about the Protokoll configuration.
+
+**Response Format**:
+```json
+{
+  "hasContext": true,
+  "discoveredDirectories": [
+    {
+      "path": "/home/user/project/.protokoll",
+      "level": 0,
+      "isPrimary": true
+    },
+    {
+      "path": "/home/user/.protokoll",
+      "level": 1,
+      "isPrimary": false
+    }
+  ],
+  "entityCounts": {
+    "projects": 5,
+    "people": 12,
+    "terms": 8,
+    "companies": 3,
+    "ignored": 2
+  },
+  "config": {
+    "outputDirectory": "~/notes",
+    "outputStructure": "month",
+    "model": "gpt-5.2",
+    "smartAssistance": {
+      "enabled": true,
+      "phoneticModel": "gpt-5-nano",
+      "analysisModel": "gpt-5-mini"
+    }
+  },
+  "resourceUris": {
+    "projects": "protokoll://entities/project",
+    "people": "protokoll://entities/person",
+    "terms": "protokoll://entities/term",
+    "companies": "protokoll://entities/company"
+  }
+}
+```
+
+**Use Cases**:
+- Understand the current configuration
+- Discover available context directories
+- Check entity counts before querying
+
+## Dynamic Resources
+
+When you call `resources/list`, Protokoll returns a list of dynamic resources based on the current context:
+
+1. **Current Configuration**: Link to the active configuration
+2. **Inbound Audio Files**: Link to audio files waiting to be processed
+3. **Processed Audio Files**: Link to processed audio files (if configured)
+4. **Entity Lists**: Links to all entity types with counts
+5. **Recent Transcripts**: Link to the 10 most recent transcripts
+
+## Usage Examples
+
+### Check for Audio Files to Process
+
+```typescript
+// List resources to find inbound audio
+const resources = await client.listResources();
+const inboundAudio = resources.resources.find(r => 
+  r.name === 'Inbound Audio Files'
+);
+
+// Read the inbound audio resource
+const audioList = await client.readResource(inboundAudio.uri);
+const data = JSON.parse(audioList.text);
+
+console.log(`Found ${data.count} audio files to process`);
+data.files.forEach(file => {
+  console.log(`- ${file.filename} (${file.sizeHuman})`);
+});
+```
+
+### Browse Recent Transcripts
+
+```typescript
+// Get recent transcripts
+const resources = await client.listResources();
+const recentTranscripts = resources.resources.find(r => 
+  r.name === 'Recent Transcripts'
+);
+
+const transcriptList = await client.readResource(recentTranscripts.uri);
+const data = JSON.parse(transcriptList.text);
+
+// Read the most recent transcript
+const latest = data.transcripts[0];
+const transcript = await client.readResource(latest.uri);
+console.log(transcript.text);
+```
+
+### Explore Context Entities
+
+```typescript
+// List all projects
+const projectsUri = 'protokoll://entities/project';
+const projectsList = await client.readResource(projectsUri);
+const projects = JSON.parse(projectsList.text);
+
+// Read details for a specific project
+const project = projects.entities[0];
+const projectDetails = await client.readResource(project.uri);
+console.log(projectDetails.text); // YAML format
+```
+
+## Resource Discovery Workflow
+
+1. **Start with `resources/list`**: Get dynamic resources for the current context
+2. **Check configuration**: Read the config resource to understand the setup
+3. **Explore entities**: Use entity list resources to discover available context
+4. **Access specific data**: Use individual resource URIs to read specific items
+
+## Notes
+
+- All audio and transcript paths are absolute paths
+- File sizes are provided in both bytes and human-readable format
+- Transcripts are sorted by date (newest first)
+- Entity lists include URIs for easy navigation
+- Resources are read-only; use tools for modifications

package/docs/MCP_RESOURCES_IMPLEMENTATION.md

@@ -0,0 +1,278 @@
+# MCP Resources Implementation Summary
+
+## Overview
+
+This document describes the implementation of comprehensive MCP resources for Protokoll, providing AI assistants with discoverable, queryable access to audio files, transcripts, and context entities.
+
+## What Was Implemented
+
+### 1. Audio Resources
+
+#### Inbound Audio Resource
+- **URI**: `protokoll://audio/inbound?directory={directory}`
+- **Purpose**: Lists audio files waiting to be processed
+- **Features**:
+  - Automatic directory discovery from config
+  - File metadata (size, modified date, extension)
+  - Human-readable file sizes
+  - Sorted by modification time (newest first)
+  - Supports all configured audio extensions
+
+#### Processed Audio Resource
+- **URI**: `protokoll://audio/processed?directory={directory}`
+- **Purpose**: Lists audio files that have been processed
+- **Features**: Same as inbound audio resource
+
+### 2. Enhanced Dynamic Resources
+
+The `resources/list` endpoint now returns dynamic resources based on the current context:
+
+1. **Current Configuration**: Active Protokoll configuration
+2. **Inbound Audio Files**: Audio files ready to process
+3. **Processed Audio Files**: Previously processed audio files
+4. **Entity Lists**: All entity types (projects, people, terms, companies) with counts
+5. **Recent Transcripts**: 10 most recent transcripts in the output directory
+
+This makes resources discoverable without requiring the client to know specific URIs.
+
+### 3. Type System Updates
+
+#### New Resource Types
+- `audio-inbound`: Inbound audio files
+- `audio-processed`: Processed audio files
+
+#### New URI Types
+- `AudioInboundUri`: Parsed inbound audio URI
+- `AudioProcessedUri`: Parsed processed audio URI
+
+### 4. URI Parser Enhancements
+
+Added support for parsing audio URIs:
+- `protokoll://audio/inbound`
+- `protokoll://audio/inbound?directory=/path`
+- `protokoll://audio/processed`
+- `protokoll://audio/processed?directory=/path`
+
+### 5. URI Builder Functions
+
+New builder functions:
+- `buildAudioInboundUri(directory?: string)`
+- `buildAudioProcessedUri(directory?: string)`
+
+### 6. Resource Reader Functions
+
+New reader functions:
+- `readAudioInboundResource(directory?: string)`
+- `readAudioProcessedResource(directory?: string)`
+- `listAudioFiles(directory: string)` (helper)
+- `formatBytes(bytes: number)` (utility)
+
+## File Changes
+
+### Modified Files
+
+1. **src/mcp/resources.ts**
+   - Added audio resource templates
+   - Enhanced `getDynamicResources()` to include audio and entity list resources
+   - Added `listAudioFiles()` helper function
+   - Added `readAudioInboundResource()` and `readAudioProcessedResource()`
+   - Added `formatBytes()` utility function
+   - Updated `handleReadResource()` to handle audio resources
+
+2. **src/mcp/types.ts**
+   - Added `audio-inbound` and `audio-processed` to `ResourceType`
+   - Added `AudioInboundUri` interface
+   - Added `AudioProcessedUri` interface
+
+3. **src/mcp/uri.ts**
+   - Added imports for new URI types
+   - Added `parseAudioUri()` function
+   - Updated `parseUri()` to handle audio URIs
+   - Added `buildAudioInboundUri()` function
+   - Added `buildAudioProcessedUri()` function
+   - Updated `getResourceType()` to recognize audio URIs
+
+4. **tests/mcp/uri.test.ts**
+   - Added tests for parsing audio URIs (5 tests)
+   - Added tests for building audio URIs (4 tests)
+   - Added tests for `getResourceType()` with audio URIs (2 tests)
+   - Total: 39 tests (all passing)
+
+### New Files
+
+1. **docs/MCP_RESOURCES.md**
+   - Comprehensive documentation of all resource types
+   - Usage examples
+   - Response format specifications
+   - Resource discovery workflow
+
+2. **docs/MCP_RESOURCES_IMPLEMENTATION.md** (this file)
+   - Implementation summary
+   - Technical details
+   - Design decisions
+
+## Design Decisions
+
+### 1. Audio File Discovery
+
+Audio files are discovered by:
+1. Reading the directory specified in the URI parameter
+2. Falling back to the config's `inputDirectory` or `processedDirectory`
+3. Filtering files by extension using `DEFAULT_AUDIO_EXTENSIONS`
+4. Sorting by modification time (newest first)
+
+### 2. Dynamic Resource Generation
+
+Dynamic resources are generated when `resources/list` is called:
+- Provides immediate visibility into available data
+- Includes entity counts to help clients decide whether to query
+- Uses the current context to determine what's available
+- Returns empty list if no context is found (graceful degradation)
+
+### 3. Error Handling
+
+- Returns empty array if directory doesn't exist (ENOENT)
+- Throws error if context is not available
+- Validates URI format and throws descriptive errors
+- Handles missing optional parameters gracefully
+
+### 4. File Size Formatting
+
+Human-readable file sizes are provided alongside raw bytes:
+- Makes it easier for AI assistants to communicate with users
+- Uses standard units (B, KB, MB, GB)
+- Rounds to 2 decimal places
+
+### 5. URI Structure
+
+Audio URIs follow the pattern:
+- `protokoll://audio/{type}?directory={path}`
+- Type is either `inbound` or `processed`
+- Directory parameter is optional (falls back to config)
+
+This structure:
+- Groups related resources under `/audio`
+- Clearly distinguishes between inbound and processed
+- Allows directory override without requiring config changes
+
+## Testing
+
+### Test Coverage
+
+- 39 URI tests (all passing)
+- 100% coverage of URI parsing and building functions
+- Tests for:
+  - Parsing audio URIs with and without directory
+  - Building audio URIs with and without directory
+  - Resource type detection for audio URIs
+  - Invalid audio type handling
+
+### Manual Testing Checklist
+
+- [ ] List resources returns audio resources when context is available
+- [ ] Read inbound audio resource returns correct file list
+- [ ] Read processed audio resource returns correct file list
+- [ ] Audio files are sorted by modification time
+- [ ] File sizes are formatted correctly
+- [ ] Directory parameter override works
+- [ ] Fallback to config directories works
+- [ ] Empty directory returns empty file list
+- [ ] Non-existent directory returns empty file list
+- [ ] Invalid audio type throws error
+
+## Integration Points
+
+### 1. Context System
+
+Resources integrate with the context system to:
+- Discover input and output directories
+- Load entity data for entity list resources
+- Determine if context is available
+
+### 2. Configuration
+
+Resources use configuration to:
+- Get default input directory (`inputDirectory`)
+- Get processed directory (`processedDirectory`)
+- Get output directory for transcripts (`outputDirectory`)
+
+### 3. Audio Tools
+
+Audio resources complement the audio tools:
+- Tools process audio files
+- Resources discover and list audio files
+- Together they provide complete audio workflow visibility
+
+## Future Enhancements
+
+### Potential Additions
+
+1. **Audio File Metadata Resource**
+   - `protokoll://audio/file/{path}`
+   - Detailed metadata for a specific audio file
+   - Duration, format, bitrate, etc.
+
+2. **Transcript Search Resource**
+   - `protokoll://transcripts/search?query={text}`
+   - Full-text search across transcripts
+   - Returns matching transcripts with context
+
+3. **Entity Search Resource**
+   - `protokoll://entities/search?query={text}`
+   - Search across all entity types
+   - Returns matching entities with relevance scores
+
+4. **Recent Activity Resource**
+   - `protokoll://activity/recent?limit={n}`
+   - Recent transcriptions, entity changes, etc.
+   - Provides activity timeline
+
+5. **Statistics Resource**
+   - `protokoll://stats`
+   - Aggregate statistics (total transcripts, audio files, entities)
+   - Processing history and trends
+
+### Subscription Support
+
+Currently, resources have `subscribe: false` in the server capabilities. Future versions could support:
+- Notifications when new audio files appear
+- Notifications when transcripts are created
+- Notifications when entities are modified
+
+This would enable real-time monitoring and reactive workflows.
+
+## Performance Considerations
+
+### Current Implementation
+
+- File listing uses `readdir()` with `withFileTypes: true` for efficiency
+- Stat calls are made only for matching audio files
+- Sorting is done in-memory (acceptable for typical directory sizes)
+- No caching (resources are read fresh each time)
+
+### Scalability
+
+For large directories (1000+ files):
+- Consider adding pagination to audio resources
+- Consider adding file count limits
+- Consider caching with TTL
+- Consider background indexing for search
+
+## Conclusion
+
+This implementation provides comprehensive resource discovery for Protokoll's MCP server. AI assistants can now:
+
+1. **Discover available data** through dynamic resources
+2. **Query audio files** waiting to be processed or already processed
+3. **Browse transcripts** with filtering and pagination
+4. **Explore context entities** to understand available knowledge
+5. **Access configuration** to understand the current setup
+
+The implementation follows MCP best practices:
+- Resources are read-only (modifications use tools)
+- URIs are structured and predictable
+- Response formats are consistent and well-documented
+- Error handling is graceful and informative
+- Type system is comprehensive and type-safe
+
+This foundation enables powerful workflows where AI assistants can autonomously discover, query, and process audio files and transcripts.