Skip to main content

ADR-007: MCP Prompts and Resources Integration for AI Assistance

id: 007-mcp-prompts-and-resources-integration title: 'ADR-007: MCP Prompts and Resources Integration' sidebar_label: 'ADR-7: MCP Prompts and Resources Integration' sidebar_position: 7​

Status​

Proposed

Context​

DocuMCP needs AI assistance capabilities, and the Model Context Protocol provides native support for exactly this use case through Prompts and Resources. Rather than extending the protocol, we should leverage MCP's built-in capabilities:

  • MCP Prompts: Pre-written templates that help users accomplish specific tasks
  • MCP Resources: File-like data that can be read by clients (like API responses, file contents, or generated documentation)

Current MCP Core Concepts that we can utilize:

  1. Tools: Interactive functions (already implemented - analyze_repository, recommend_ssg, etc.)
  2. Prompts: Template-based assistance for common workflows
  3. Resources: Readable data and content that clients can access

This approach maintains full MCP compliance while providing rich AI assistance through the protocol's intended mechanisms.

Decision​

We will implement AI assistance using MCP's native Prompts and Resources capabilities, providing pre-written prompt templates for documentation workflows and exposing generated content through the MCP resource system.

Core Implementation Strategy:​

1. MCP Prompts for Documentation Workflows​

// Implement MCP ListPromptsRequestSchema and GetPromptRequestSchema
const DOCUMENTATION_PROMPTS = [
  {
    name: "analyze-and-recommend",
    description: "Complete repository analysis and SSG recommendation workflow",
    arguments: [
      { name: "repository_path", description: "Path to repository", required: true },
      { name: "priority", description: "Priority: simplicity, features, performance" }
    ]
  },
  {
    name: "setup-documentation",
    description: "Create comprehensive documentation structure with best practices",
    arguments: [
      { name: "project_name", description: "Project name", required: true },
      { name: "ssg_type", description: "Static site generator type" }
    ]
  },
  {
    name: "troubleshoot-deployment",
    description: "Diagnose and fix GitHub Pages deployment issues", 
    arguments: [
      { name: "repository_url", description: "GitHub repository URL", required: true },
      { name: "error_message", description: "Deployment error message" }
    ]
  }
];

2. MCP Resources for Generated Content​

// Implement ListResourcesRequestSchema and ReadResourceRequestSchema  
interface DocuMCPResource {
  uri: string;        // e.g., "documcp://analysis/repo-123"
  name: string;       // Human-readable name
  description: string; // What this resource contains
  mimeType: string;   // Content type
}

// Resource types we'll expose:
const RESOURCE_TYPES = [
  "documcp://analysis/{analysisId}",      // Repository analysis results
  "documcp://config/{ssgType}/{projectId}", // Generated configuration files
  "documcp://structure/{projectId}",      // Documentation structure templates
  "documcp://deployment/{workflowId}",    // GitHub Actions workflows
  "documcp://templates/{templateType}",   // Reusable templates
];

3. Integration with Existing Tools​

  • Tools remain unchanged: analyze_repository, recommend_ssg, generate_config, etc.
  • Prompts provide workflows: Chain multiple tool calls with guided prompts
  • Resources expose results: Make tool outputs accessible as MCP resources

Example Workflow Integration:​

// MCP Prompt: "analyze-and-recommend"
// Generated prompt text that guides the user through:
// 1. Call analyze_repository tool
// 2. Review analysis results via documcp://analysis/{id} resource  
// 3. Call recommend_ssg tool with analysis results
// 4. Access recommendations via documcp://recommendations/{id} resource
// 5. Call generate_config with selected SSG

Alternatives Considered​

Alternative 1: Custom Protocol Extensions (Previous Approach)​

  • Pros: Maximum flexibility, custom AI features
  • Cons: Protocol complexity, compatibility issues, non-standard
  • Decision: Rejected in favor of MCP-native approach

Alternative 2: Tools-Only Approach​

  • Pros: Simple, already implemented
  • Cons: No guided workflows, no template assistance, harder user experience
  • Decision: Insufficient for comprehensive AI assistance

Alternative 3: External AI Service Integration​

  • Pros: Leverage existing AI platforms
  • Cons: Breaks MCP cohesion, additional dependencies, latency
  • Decision: Conflicts with MCP server simplicity

Consequences​

Positive Consequences​

  • MCP Compliance: Uses protocol as designed, no custom extensions needed
  • Client Compatibility: Works with all MCP clients (Claude Desktop, GitHub Copilot, etc.)
  • Guided Workflows: Prompts provide step-by-step assistance for complex tasks
  • Rich Content Access: Resources make generated content easily accessible
  • Template Reusability: Prompts can be customized and reused across projects
  • Simplified Architecture: No need for custom protocol handling or AI-specific interfaces

Negative Consequences​

  • Prompt Complexity: Complex workflows require sophisticated prompt engineering
  • Resource Management: Need efficient resource caching and lifecycle management
  • Limited AI Features: Constrained to MCP's prompt/resource model
  • Template Maintenance: Prompts need regular updates as tools evolve

Implementation Plan​

Phase 1: Core MCP Integration (Week 1-2)​

  1. Implement ListPromptsRequestSchema and GetPromptRequestSchema handlers
  2. Implement ListResourcesRequestSchema and ReadResourceRequestSchema handlers
  3. Create resource URI schema and routing system
  4. Add MCP capabilities registration for prompts and resources

Phase 2: Documentation Prompts (Week 3-4)​

  1. Create "analyze-and-recommend" workflow prompt
  2. Create "setup-documentation" structure prompt
  3. Create "troubleshoot-deployment" diagnostic prompt
  4. Add prompt argument validation and help text

Phase 3: Resource Management (Week 5-6)​

  1. Implement resource caching for analysis results
  2. Add generated configuration file resources
  3. Create template library resources
  4. Add resource cleanup and lifecycle management

Phase 4: Advanced Features (Week 7-8)​

  1. Dynamic prompt generation based on project characteristics
  2. Contextual resource recommendations
  3. Prompt composition for complex workflows
  4. Integration testing with major MCP clients

Integration with Existing Architecture​

ADR-001 (MCP Server Architecture)​

  • Extends the TypeScript MCP SDK usage to include prompts and resources
  • Maintains stateless operation model
  • Leverages existing modular design

ADR-006 (MCP Tools API Design)​

  • Tools remain the primary interface for actions
  • Prompts provide guided workflows using existing tools
  • Resources expose tool outputs in structured format

ADR-007 (Pluggable Prompt Tool Architecture)​

  • Modified Approach: Instead of custom prompt engines, use MCP prompts
  • Template system becomes MCP prompt templates
  • Configuration-driven approach still applies for prompt customization

MCP Server Capabilities Declaration​

server.setRequestHandler(InitializeRequestSchema, async () => ({
  protocolVersion: "2024-11-05",
  capabilities: {
    tools: {},           // Existing tool capabilities
    prompts: {},         // NEW: Prompt template capabilities  
    resources: {},       // NEW: Resource access capabilities
  },
  serverInfo: {
    name: "documcp",
    version: "0.2.0",
  },
}));

Future Considerations​

  • Integration with MCP sampling for AI-powered responses
  • Advanced prompt chaining and conditional workflows
  • Resource subscriptions for real-time updates
  • Community prompt template sharing and marketplace