The documentation resources feature provides comprehensive developer documentation through the MCP resources interface. This allows AI assistants and tools to access API documentation, integration guides, error references, and examples directly through resource URIs.
Overview
Documentation resources are static resources that are built at compile time and embedded into the server bundle. This approach ensures:
- Fast access without file I/O
- Version-controlled documentation
- Consistent content across deployments
- No runtime dependencies on the file system
Architecture
Build Process
┌──────────────────────────────────┐
│ Source Documentation Files │
│ src/resources/docs/*.md/*.yaml │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ Build Script Execution │
│ scripts/build-docs.ts │
│ • Read all .md and .yaml files │
│ • Generate TypeScript exports │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ Generated TypeScript │
│ src/resources/docs/index.ts │
│ • Export constants for each doc │
│ • Escaped content strings │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ TypeScript Compilation │
│ • Bundle docs into dist/ │
│ • No runtime file access needed │
└──────────────┬───────────────────┘
│
▼
┌──────────────────────────────────┐
│ Runtime Access via MCP │
│ • List documentation resources │
│ • Read content by URI │
└──────────────────────────────────┘
Implementation Details
Build Script
The build script (scripts/build-docs.ts
) performs the following steps:
import { readFileSync, readdirSync, writeFileSync } from 'fs';
import { join } from 'path';
const DOCS_DIR = join(__dirname, '../src/resources/docs');
const OUTPUT_FILE = join(DOCS_DIR, 'index.ts');
// Read all documentation files
const docFiles = readdirSync(DOCS_DIR).filter(file =>
file.endsWith('.md') || file.endsWith('.yaml')
);
// Generate TypeScript exports
let exports = '// Auto-generated file - DO NOT EDIT\n\n';
for (const file of docFiles) {
const content = readFileSync(join(DOCS_DIR, file), 'utf-8');
const baseName = file.replace(/\.(md|yaml)$/, '');
const constName = baseName.toUpperCase().replace(/-/g, '_') + '_DOC';
// Escape backticks and template literals
const escapedContent = content
.replace(/`/g, '\\`')
.replace(/\${/g, '\\${');
exports += `export const ${constName} = \`${escapedContent}\`;\n\n`;
}
writeFileSync(OUTPUT_FILE, exports);
Resource Handler Integration
The ResourceHandler class includes documentation resources in its listing and reading methods:
import {
AIRUNTIMESECURITYAPI_DOC,
ERRORCODES_DOC,
USECASES_DOC,
SCANSERVICE_DOC,
INTEGRATION_GUIDE_DOC,
SECURITY_FEATURES_DOC,
} from './docs';
// Documentation resource metadata
const DOCUMENTATION_RESOURCES = {
'airuntimesecurityapi': {
content: AIRUNTIMESECURITYAPI_DOC,
mimeType: 'text/markdown',
name: 'Prisma AIRS AI Runtime API Intercept',
description: 'Complete API reference and overview for Prisma AIRS',
},
'errorcodes': {
content: ERRORCODES_DOC,
mimeType: 'text/markdown',
name: 'Error Codes Reference',
description: 'Comprehensive list of error codes and their meanings',
},
'usecases': {
content: USECASES_DOC,
mimeType: 'text/markdown',
name: 'Use Cases Guide',
description: 'Example use cases and implementation patterns',
},
'scanservice': {
content: SCANSERVICE_DOC,
mimeType: 'application/x-yaml',
name: 'OpenAPI Specification',
description: 'OpenAPI 3.0 specification for Prisma AIRS scan service',
},
'integration-guide': {
content: INTEGRATION_GUIDE_DOC,
mimeType: 'text/markdown',
name: 'Integration Guide',
description: 'Step-by-step guide for integrating Prisma AIRS',
},
'security-features': {
content: SECURITY_FEATURES_DOC,
mimeType: 'text/markdown',
name: 'Security Features Guide',
description: 'Detailed documentation of security features and capabilities',
},
};
Available Documentation
API Documentation (airuntimesecurityapi
)
URI: airs://developer-docs/airuntimesecurityapi
Type: Markdown
Content: Complete API reference including endpoints, authentication, request/response formats, and examples.
Error Codes (errorcodes
)
URI: airs://developer-docs/errorcodes
Type: Markdown
Content: Comprehensive list of all error codes with descriptions and resolution steps.
Use Cases (usecases
)
URI: airs://developer-docs/usecases
Type: Markdown
Content: Real-world use cases with implementation examples and best practices.
OpenAPI Specification (scanservice
)
URI: airs://developer-docs/scanservice
Type: YAML
Content: Complete OpenAPI 3.0 specification for the Prisma AIRS scan service.
Integration Guide (integration-guide
)
URI: airs://developer-docs/integration-guide
Type: Markdown
Content: Step-by-step integration instructions with code examples.
Security Features (security-features
)
URI: airs://developer-docs/security-features
Type: Markdown
Content: Detailed documentation of all security features and threat detection capabilities.
Usage Examples
Listing Documentation Resources
# List all resources (includes documentation)
curl -X POST http://localhost:3000/ \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "resources/list",
"params": {}
}'
# Response includes:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"resources": [
{
"uri": "airs://developer-docs/airuntimesecurityapi",
"name": "Prisma AIRS AI Runtime API Intercept",
"description": "Complete API reference and overview for Prisma AIRS",
"mimeType": "text/markdown"
},
// ... other documentation resources
]
}
}
Reading Documentation Content
# Read API documentation
curl -X POST http://localhost:3000/ \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "2",
"method": "resources/read",
"params": {
"uri": "airs://developer-docs/airuntimesecurityapi"
}
}'
# Response:
{
"jsonrpc": "2.0",
"id": "2",
"result": {
"contents": [{
"uri": "airs://developer-docs/airuntimesecurityapi",
"mimeType": "text/markdown",
"text": "# Prisma AIRS AI Runtime API Intercept\n\n..."
}]
}
}
JavaScript/TypeScript Client
// Using an MCP client library
const client = new MCPClient('http://localhost:3000');
// List all documentation resources
const resources = await client.listResources();
const docs = resources.filter(r =>
r.uri.startsWith('airs://developer-docs/')
);
// Read specific documentation
const apiDocs = await client.readResource(
'airs://developer-docs/airuntimesecurityapi'
);
console.log(apiDocs.contents[0].text);
// Read OpenAPI specification
const openapi = await client.readResource(
'airs://developer-docs/scanservice'
);
const spec = yaml.parse(openapi.contents[0].text);
Benefits
1. Performance
- No runtime file I/O operations
- Content served from memory
- Fast response times
- Reduced server load
2. Reliability
- Documentation always available
- No file system dependencies
- Consistent across deployments
- Version-controlled content
3. Security
- No direct file system access
- Content validated at build time
- Safe from path traversal attacks
- Controlled access through MCP
4. Developer Experience
- Easy to update documentation
- Automatic TypeScript type checking
- IDE support for content
- Simple testing process
Adding New Documentation
To add new documentation resources:
-
Create Documentation File
# Add markdown file echo "# My New Guide" > src/resources/docs/my-guide.md # Or add YAML file echo "version: 1.0" > src/resources/docs/config.yaml
- Update Build Script (if needed)
- The script automatically picks up new files
- No changes needed for standard .md/.yaml files
-
Add Metadata
// In src/resources/index.ts const DOCUMENTATION_RESOURCES = { // ... existing resources 'my-guide': { content: MY_GUIDE_DOC, mimeType: 'text/markdown', name: 'My New Guide', description: 'Description of the guide', }, };
-
Build and Test
npm run build npm run dev # Test the new resource curl -X POST http://localhost:3000/ \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "resources/read", "params": { "uri": "airs://developer-docs/my-guide" } }'
Best Practices
1. Documentation Format
- Use clear, consistent markdown formatting
- Include code examples with syntax highlighting
- Add section headers for navigation
- Keep line lengths reasonable
2. File Naming
- Use kebab-case for file names
- Be descriptive but concise
- Match file names to resource IDs
- Use appropriate extensions (.md, .yaml)
3. Content Guidelines
- Focus on developer needs
- Include practical examples
- Explain error scenarios
- Provide troubleshooting tips
4. Maintenance
- Review documentation regularly
- Update examples with API changes
- Test documentation builds
- Monitor for broken links
Troubleshooting
Build Errors
# If build fails, check:
1. File permissions in src/resources/docs/
2. Valid UTF-8 encoding
3. Proper escaping of special characters
4. No syntax errors in YAML files
Missing Resources
# Verify documentation was built:
ls -la src/resources/docs/index.ts
# Check if resource is registered:
grep "my-guide" src/resources/index.ts
Content Issues
# Test content directly:
node -e "
const { MY_GUIDE_DOC } = require('./dist/resources/docs');
console.log(MY_GUIDE_DOC.substring(0, 100));
"
Future Enhancements
Planned Features
- Markdown Processing
- TOC generation
- Link validation
- Code syntax highlighting
- Search Capabilities
- Full-text search across docs
- Keyword indexing
- Relevance ranking
- Versioning
- Multiple doc versions
- Version selection
- Migration guides
- Localization
- Multi-language support
- Locale detection
- Translation management
Related Documentation
- Resources Overview - Module overview
- Resources Index - Implementation details
- Build Scripts - Build script documentation
- MCP Protocol - Protocol specification