Skip to content

resources-guide.md

Latest commit

 

History

History
654 lines (552 loc) · 17.1 KB

resources-guide.md

File metadata and controls

654 lines (552 loc) · 17.1 KB
Raw

BookStack MCP Resources Guide

Overview

This guide covers the Resources system in the BookStack MCP Server, which provides direct access to BookStack content through the Model Context Protocol (MCP). Resources offer a read-only interface to retrieve content, while tools provide interactive operations.

Resources vs Tools

Resources

  • Read-only access to BookStack content
  • URI-based addressing (e.g., bookstack://books/123)
  • Content retrieval in structured formats (JSON, HTML, etc.)
  • Direct data access without side effects
  • Cacheable and suitable for context loading

Tools

  • Interactive operations (create, update, delete)
  • Parameter-based input with validation
  • State-changing operations on BookStack
  • Error handling with retry policies
  • Action-oriented functionality

Available Resource Types

The BookStack MCP Server provides 12 resource types across 6 categories:

1. Book Resources

bookstack://books

  • Purpose: List all books with metadata
  • Returns: Array of book objects with pagination
  • Schema: 
    {
  "data": [
    {
      "id": 123,
      "name": "Documentation Guide",
      "slug": "documentation-guide",
      "description": "Complete guide to documentation",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 25
}
  • Use Cases:
    • Initial discovery of available content
    • Understanding documentation structure
    • Content planning and organization

bookstack://books/{id}

  • Purpose: Get specific book with complete hierarchy
  • Returns: Full book object with all chapters and pages
  • Schema: 
    {
  "id": 123,
  "name": "Documentation Guide",
  "contents": [
    {
      "type": "chapter",
      "id": 456,
      "name": "Getting Started",
      "pages": [...]
    },
    {
      "type": "page",
      "id": 789,
      "name": "Overview"
    }
  ],
  "tags": [
    {"name": "category", "value": "documentation"}
  ]
}
  • Dependencies: Requires book ID from bookstack://books
  • Use Cases:
    • Reading complete documentation structure
    • Understanding book organization
    • Pre-flight checks before structural changes

2. Page Resources

bookstack://pages

  • Purpose: List all pages across BookStack
  • Returns: Array of page objects with metadata
  • Schema: 
    {
  "data": [
    {
      "id": 789,
      "book_id": 123,
      "chapter_id": 456,
      "name": "Getting Started",
      "draft": false,
      "template": false,
      "priority": 1
    }
  ],
  "total": 150
}
  • Use Cases:
    • Content discovery across all books
    • Finding specific pages by name
    • Understanding page distribution

bookstack://pages/{id}

  • Purpose: Get specific page with full content
  • Returns: Complete page object with HTML and markdown
  • Schema: 
    {
  "id": 789,
  "name": "Getting Started",
  "html": "<p>Welcome to our documentation...</p>",
  "markdown": "# Getting Started\n\nWelcome to our documentation...",
  "tags": [
    {"name": "section", "value": "intro"}
  ]
}
  • Dependencies: Requires page ID from bookstack://pages
  • Use Cases:
    • Reading complete page content
    • Content analysis and processing
    • Documentation generation

3. Chapter Resources

bookstack://chapters

  • Purpose: List all chapters across BookStack
  • Returns: Array of chapter objects with metadata
  • Schema: 
    {
  "data": [
    {
      "id": 456,
      "book_id": 123,
      "name": "Getting Started",
      "description": "Introduction to the system",
      "priority": 1
    }
  ],
  "total": 45
}
  • Use Cases:
    • Understanding chapter organization
    • Content structure analysis
    • Chapter-level operations planning

bookstack://chapters/{id}

  • Purpose: Get specific chapter with all pages
  • Returns: Complete chapter object with nested pages
  • Schema: 
    {
  "id": 456,
  "name": "Getting Started",
  "pages": [
    {
      "id": 789,
      "name": "Overview",
      "priority": 1
    },
    {
      "id": 790,
      "name": "Installation",
      "priority": 2
    }
  ]
}
  • Dependencies: Requires chapter ID from bookstack://chapters
  • Use Cases:
    • Reading chapter structure
    • Understanding page organization within chapters
    • Content hierarchy analysis

4. Shelf Resources

bookstack://shelves

  • Purpose: List all bookshelves (collections)
  • Returns: Array of shelf objects with metadata
  • Schema: 
    {
  "data": [
    {
      "id": 321,
      "name": "Technical Documentation",
      "description": "All technical guides and manuals",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 8
}
  • Use Cases:
    • Understanding content organization
    • Discovering related book collections
    • Content categorization analysis

bookstack://shelves/{id}

  • Purpose: Get specific shelf with all books
  • Returns: Complete shelf object with nested books
  • Schema: 
    {
  "id": 321,
  "name": "Technical Documentation",
  "books": [
    {
      "id": 123,
      "name": "API Guide",
      "description": "Complete API documentation"
    },
    {
      "id": 124,
      "name": "Installation Guide",
      "description": "Step-by-step installation"
    }
  ]
}
  • Dependencies: Requires shelf ID from bookstack://shelves
  • Use Cases:
    • Understanding shelf organization
    • Content collection analysis
    • Related content discovery

5. User Resources

bookstack://users

  • Purpose: List all users in the system
  • Returns: Array of user objects with metadata
  • Schema: 
    {
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "slug": "john-doe",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 25
}
  • Use Cases:
    • User discovery and analysis
    • Author information retrieval
    • User-based content filtering

bookstack://users/{id}

  • Purpose: Get specific user with roles
  • Returns: Complete user object with role information
  • Schema: 
    {
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "roles": [
    {
      "id": 2,
      "display_name": "Editor",
      "description": "Can edit content"
    }
  ]
}
  • Dependencies: Requires user ID from bookstack://users
  • Use Cases:
    • User profile information
    • Permission analysis
    • Content ownership tracking

6. Search Resources

bookstack://search/{query}

  • Purpose: Search across all content types
  • Returns: Array of search results with snippets
  • Schema: 
    {
  "data": [
    {
      "id": 123,
      "name": "API Authentication",
      "type": "page",
      "preview_html": {
        "name": "API <em>Authentication</em>",
        "content": "Learn how to authenticate with the API..."
      },
      "book": {
        "id": 456,
        "name": "API Guide"
      }
    }
  ],
  "total": 12
}
  • URI Format: Encode queries in the URI (e.g., bookstack://search/API%20authentication)
  • Use Cases:
    • Content discovery
    • Finding relevant information
    • Cross-content search

Resource Schemas

Enhanced Schema Features

The BookStack MCP resources include enhanced schema definitions with:

  • JSON Schema validation for all resource types
  • Example responses with realistic data
  • Access patterns describing common usage scenarios
  • Dependency information showing resource relationships

Schema Properties

All resources include these standard properties:

  • uri: Resource identifier pattern
  • name: Human-readable name
  • description: Detailed description of the resource
  • mimeType: Content type (typically application/json)
  • schema: JSON Schema definition
  • examples: Usage examples with expected formats
  • access_patterns: Common usage scenarios
  • dependencies: Related resources (where applicable)

Integration Patterns with Claude

1. Content Discovery Pattern

// Step 1: Discover available books
const books = await readResource('bookstack://books');

// Step 2: Get specific book structure
const book = await readResource(`bookstack://books/${bookId}`);

// Step 3: Read specific pages
const pages = await Promise.all(
  book.contents
    .filter(item => item.type === 'page')
    .map(page => readResource(`bookstack://pages/${page.id}`))
);

2. Search-First Pattern

// Step 1: Search for relevant content
const results = await readResource('bookstack://search/authentication');

// Step 2: Access specific results
const relevantPages = await Promise.all(
  results.data
    .filter(item => item.type === 'page')
    .map(item => readResource(`bookstack://pages/${item.id}`))
);

3. Hierarchical Navigation Pattern

// Step 1: Get shelf organization
const shelf = await readResource(`bookstack://shelves/${shelfId}`);

// Step 2: Navigate to specific book
const book = await readResource(`bookstack://books/${bookId}`);

// Step 3: Read chapter contents
const chapter = await readResource(`bookstack://chapters/${chapterId}`);

// Step 4: Access individual pages
const page = await readResource(`bookstack://pages/${pageId}`);

4. Batch Content Loading Pattern

// Load multiple resources in parallel
const [books, users, shelves] = await Promise.all([
  readResource('bookstack://books'),
  readResource('bookstack://users'),
  readResource('bookstack://shelves')
]);

URI Patterns and Examples

Static URIs

  • bookstack://books - All books
  • bookstack://pages - All pages
  • bookstack://chapters - All chapters
  • bookstack://shelves - All shelves
  • bookstack://users - All users

Dynamic URIs

  • bookstack://books/{id} - Specific book (e.g., bookstack://books/123)
  • bookstack://pages/{id} - Specific page (e.g., bookstack://pages/456)
  • bookstack://chapters/{id} - Specific chapter (e.g., bookstack://chapters/789)
  • bookstack://shelves/{id} - Specific shelf (e.g., bookstack://shelves/321)
  • bookstack://users/{id} - Specific user (e.g., bookstack://users/1)
  • bookstack://search/{query} - Search results (e.g., bookstack://search/API%20guide)

URI Encoding

  • Spaces: Use %20 (e.g., bookstack://search/API%20guide)
  • Special characters: URL encode as needed
  • Multiple words: Encode each space separately

Error Handling

Common Resource Errors

  1. Resource Not Found

    • Cause: Invalid ID or URI pattern
    • Solution: Verify resource exists using list resources first
    • Example: bookstack://books/999 where book 999 doesn't exist

  2. Invalid URI Format

    • Cause: Malformed URI or incorrect pattern
    • Solution: Follow URI pattern guidelines exactly
    • Example: bookstack://book/123 (missing 's' in 'books')

  3. Permission Denied

    • Cause: Insufficient permissions for requested content
    • Solution: Check user permissions or authenticate properly
    • Example: Private content not accessible to current user

  4. API Connection Error

    • Cause: BookStack server unreachable or API token invalid
    • Solution: Verify server configuration and API token
    • Example: Server down or network connectivity issues

Error Recovery Patterns

  1. Graceful Degradation

    try {
  const book = await readResource(`bookstack://books/${bookId}`);
  return book;
} catch (error) {
  // Fall back to basic book list
  const books = await readResource('bookstack://books');
  return books.data.find(b => b.id === bookId);
}

  2. Retry with Backoff

    async function readResourceWithRetry(uri, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await readResource(uri);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Performance Considerations

Resource Loading Strategies

  1. Lazy Loading

    • Load resources only when needed
    • Ideal for large hierarchies
    • Reduces initial load time

  2. Parallel Loading

    • Load multiple independent resources simultaneously
    • Improves overall performance
    • Good for batch operations

  3. Caching

    • Cache frequently accessed resources
    • Implement TTL for data freshness
    • Reduce API calls

Best Practices

  1. Start with Lists

    • Always begin with list resources (bookstack://books)
    • Use IDs from lists to access specific items
    • Avoids guessing resource identifiers

  2. Batch Related Operations

    • Load all related resources in parallel
    • Reduce sequential API calls
    • Improve user experience

  3. Handle Hierarchies Efficiently

    • Use book resources to understand structure
    • Navigate hierarchy systematically
    • Avoid deep recursive loading

  4. Implement Proper Error Handling

    • Always handle resource not found errors
    • Provide meaningful error messages
    • Implement retry logic for transient failures

Advanced Usage

Resource Filtering and Searching

While resources provide raw data, you can implement client-side filtering:

// Filter books by name
const books = await readResource('bookstack://books');
const filteredBooks = books.data.filter(book => 
  book.name.toLowerCase().includes('api')
);

// Search across multiple resource types
const searchResults = await readResource('bookstack://search/authentication');
const pageResults = searchResults.data.filter(item => item.type === 'page');

Content Aggregation

Combine multiple resources for comprehensive content views:

// Get complete documentation overview
const [books, users, shelves] = await Promise.all([
  readResource('bookstack://books'),
  readResource('bookstack://users'),
  readResource('bookstack://shelves')
]);

const overview = {
  totalBooks: books.total,
  totalUsers: users.total,
  totalShelves: shelves.total,
  recentBooks: books.data.slice(0, 5),
  activeUsers: users.data.filter(user => user.last_activity_at)
};

Dynamic Resource Discovery

Use resource metadata for dynamic applications:

// Discover available resources
const resources = await listResources();
const bookResources = resources.filter(r => r.uri.includes('books'));

// Build dynamic navigation
const navigation = await Promise.all(
  bookResources.map(async resource => {
    if (resource.uri === 'bookstack://books') {
      const books = await readResource(resource.uri);
      return {
        title: 'Books',
        count: books.total,
        items: books.data
      };
    }
  })
);

Troubleshooting

Common Issues

  1. Empty Results

    • Check: Resource exists and has data
    • Solution: Verify BookStack content exists
    • Debug: Use list resources first

  2. Slow Performance

    • Check: Number of API calls
    • Solution: Implement parallel loading
    • Debug: Monitor API response times

  3. Inconsistent Data

    • Check: Cache invalidation
    • Solution: Implement proper cache TTL
    • Debug: Compare cached vs fresh data

Debugging Tips

  1. Enable Debug Logging

    // Set LOG_LEVEL=debug in environment
process.env.LOG_LEVEL = 'debug';

  2. Monitor API Calls

    // Track resource access patterns
const resourceUsage = new Map();

function trackResourceUsage(uri) {
  resourceUsage.set(uri, (resourceUsage.get(uri) || 0) + 1);
}

  3. Validate Resource URIs

    function validateResourceUri(uri) {
  const patterns = [
    /^bookstack:\/\/books$/,
    /^bookstack:\/\/books\/\d+$/,
    /^bookstack:\/\/pages$/,
    /^bookstack:\/\/pages\/\d+$/,
    // ... other patterns
  ];
  
  return patterns.some(pattern => pattern.test(uri));
}

Integration with BookStack Tools

Resources complement the BookStack MCP tools:

  • Resources provide read-only access to content
  • Tools enable content creation and modification
  • Use together for complete BookStack integration

Typical Workflow

  1. Discovery: Use resources to understand existing content
  2. Analysis: Process resource data to identify needs
  3. Action: Use tools to create or modify content
  4. Verification: Use resources to confirm changes

This creates a complete cycle of content management through the MCP interface.

Conclusion

The BookStack MCP Resources system provides comprehensive, efficient access to BookStack content through a standardized URI-based interface. By understanding the resource types, patterns, and best practices outlined in this guide, you can build robust integrations that effectively leverage BookStack's knowledge management capabilities.

For interactive operations, combine resources with the BookStack MCP tools to create complete content management workflows.