@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
174 lines • 5.86 kB
TypeScript
/**
* Capability Index Resource Handler
*
* Exposes the capability index as an MCP resource for injection into LLM context.
* Provides both summary (action_triggers only) and full index variants.
*
* ⚠️ MERGE STATUS: PORTED BUT NOT INTEGRATED (October 2025)
*
* This file was ported from main branch (v1.9.18-v1.9.24) but is NOT currently
* integrated into the refactored DI architecture. Integration is planned for a
* future phase once the Enhanced Index system is fully operational.
*
* CURRENT STATE:
* - ✅ File ported and preserved for future use
* - ❌ NOT registered in DI Container
* - ❌ NOT registered with MCP server
* - ❌ NOT accessible to users
*
* ⚠️ ORIGINAL STATUS: NON-FUNCTIONAL IN CLAUDE CODE (October 2025)
*
* This is a FUTURE-PROOF implementation. MCP Resources are currently:
* - ✅ Fully implemented and MCP specification compliant
* - ❌ NOT working in Claude Code (discovery only, never read)
* - ⚠️ Manual attachment only in Claude Desktop/VS Code
*
* WHY IMPLEMENT NOW?
* - Early adopter advantage when clients add full support
* - Manual attachment works in Claude Desktop/VS Code
* - Zero overhead when disabled (default configuration)
*
* DEFAULT: DISABLED FOR SAFETY
* Resources are disabled by default to avoid token overhead and ensure
* no surprises for users. Must be explicitly enabled in configuration.
*
* WHEN WILL THIS BE USEFUL?
* When Claude Code and other MCP clients implement the missing
* resources/read functionality and automatic resource injection.
* Expected timeline: Unknown.
*
* For detailed research, see:
* docs/development/MCP_RESOURCES_SUPPORT_RESEARCH_2025-10-16.md
*
* For user documentation, see:
* docs/configuration/MCP_RESOURCES.md
*
* FUTURE INTEGRATION TASKS:
* - [ ] Register in DI Container (src/di/Container.ts)
* - [ ] Add configuration option for enabling resources
* - [ ] Register resource handlers with MCP server when enabled
* - [ ] Add unit tests for resource generation
* - [ ] Add integration tests for MCP resource protocol
*/
import { IFileOperationsService } from '../../services/FileOperationsService.js';
/**
* Statistics about the capability index size and token estimates
*/
interface CapabilityIndexStatistics {
summarySize: number;
summaryWords: number;
summaryLines: number;
fullSize: number;
fullWords: number;
fullLines: number;
estimatedSummaryTokens: number;
estimatedFullTokens: number;
}
/**
* MCP Resource structure
*/
interface MCPResource {
uri: string;
name: string;
description: string;
mimeType: string;
}
/**
* MCP Resource list response
*/
interface MCPResourceListResponse {
resources: MCPResource[];
}
/**
* MCP Resource content item
*/
interface MCPResourceContent {
uri: string;
mimeType: string;
text: string;
}
/**
* MCP Resource read response
*/
interface MCPResourceReadResponse {
contents: MCPResourceContent[];
}
/**
* Capability Index Resource Handler
*
* Provides three MCP resources:
* 1. Summary (~2.5-3.5K tokens) - action_triggers only
* 2. Full (~35-45K tokens) - complete index with all details
* 3. Stats (JSON) - size metrics and token estimates
*
* WHY DISABLED BY DEFAULT:
* 1. Current MCP clients don't actually read resources (Claude Code discovery only)
* 2. Avoids unexpected token overhead when clients do implement reading
* 3. Provides opt-in behavior for users who want to test manually in Claude Desktop
*
* TO ENABLE:
* Set in config: resources.enabled = true
* Or environment: DOLLHOUSE_RESOURCES_ENABLED=true
*
* NOTE: This class always provides resource handlers for MCP protocol compliance,
* but the resources are only registered with the MCP server if explicitly enabled.
*/
export declare class CapabilityIndexResource {
private readonly capabilityIndexPath;
private cachedIndex;
private cacheTimestamp;
private readonly CACHE_TTL;
private readonly fileOperations;
constructor(fileOperations: IFileOperationsService);
/**
* Load and parse capability index from filesystem
* Uses 60-second cache to avoid excessive file reads
*
* @returns Parsed capability index
* @throws Error if file cannot be read or parsed
*/
private loadCapabilityIndex;
/**
* Generate summary version of capability index (metadata + action_triggers only)
* Estimated: 2,500-3,500 tokens
*
* @returns YAML string with header and summary content
*/
generateSummary(): Promise<string>;
/**
* Generate full capability index
* Estimated: 35,000-45,000 tokens
*
* @returns YAML string with header and full index content
*/
generateFull(): Promise<string>;
/**
* Get statistics about the capability index for measurement
* Provides size metrics and rough token estimates using:
* (chars/4 + words*1.3)/2 formula
*
* @returns Statistics object with size and token estimates
*/
getStatistics(): Promise<CapabilityIndexStatistics>;
/**
* MCP Resource Handler: List available resources
*
* Returns three resources:
* - summary: Lightweight index (~2.5-3.5K tokens)
* - full: Complete index (~35-45K tokens)
* - stats: Size and token metrics (JSON)
*
* @returns Resource list with URIs, names, descriptions, and MIME types
*/
listResources(): Promise<MCPResourceListResponse>;
/**
* MCP Resource Handler: Read a specific resource
*
* @param uri - Resource URI to read (must match one from listResources)
* @returns Resource content with URI, MIME type, and text
* @throws Error if URI is not recognized
*/
readResource(uri: string): Promise<MCPResourceReadResponse>;
}
export {};
//# sourceMappingURL=CapabilityIndexResource.d.ts.map