MCP server for serving AI documentation tools
npm install ai-docs-mcp-serverA Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to documentation, knowledge bases, and content management systems. This server bridges the gap between AI tools and your organization's knowledge repositories, enabling intelligent document creation, retrieval, and management across multiple platforms.
This is a production-ready MCP server that provides:
- ๐ Local Documentation Access - Read and serve markdown files from your local docs directory
- ๐ง Guru Knowledge Base Integration - Search, read, and manage Guru cards and collections
- ๐ Notion Database Management - Create, query, update, and manage documentation in Notion databases
- ๐ Advanced Query & Search - Powerful filtering, sorting, and search capabilities across all platforms
- ๐ ๏ธ Content Creation & Management - Convert markdown to Notion pages with proper metadata
- ๐ Bi-directional Sync - Export Notion pages back to markdown format
- ๐๏ธ Development & Production Modes - Flexible deployment options for different environments
Built with modern TypeScript and a clean, modular architecture:
- TypeScript/Node.js runtime (requires Node.js โฅ20.0.0)
- MCP SDK v1.12.0 for protocol implementation
- Modular tool-based design with separated concerns
- Zod validation for type safety and parameter validation
- Environment-based configuration for development and production
```
src/
โโโ index.ts # Main MCP server entry point
โโโ server.ts # Server configuration and tool registration
โโโ services/
โ โโโ notion.ts # Notion API service and database operations
โ โโโ guru.ts # Guru API service
โโโ tools/
โ โโโ docs.ts # Local documentation tools
โ โโโ guru.ts # Guru knowledge base tools
โ โโโ notion.ts # Notion database management tools
โโโ types/
โ โโโ notion.ts # Notion API type definitions
โ โโโ index.ts # General TypeScript interfaces
โโโ utils/
โโโ converters.ts # Markdown โ Notion conversion utilities
โโโ markdown-parser.ts # Advanced markdown parsing
โโโ notion-to-markdown.ts # Notion blocks to markdown conversion
โโโ markdown-to-notion.ts # Markdown to Notion blocks conversion
โโโ docs.ts # Documentation file utilities
#### legacy-list-docs
Lists all available local documentation files organized by category
- Returns: Complete inventory of markdown documentation
- Use case: Discover available local documentation before reading files
#### legacy-read-doc
Reads the content of a specific local documentation file
- Parameters:
- category (required): Document category path (e.g., 'code_guidelines/flutter', 'service-docs')name
- (required): Document name without .md extension
- Returns: Full markdown content with metadata
- Supports: Fuzzy matching for file names
#### guru-list-cards
Search and list Guru knowledge cards with advanced filtering
- Parameters:
- searchTerms (optional): Search terms for card title/contentmaxResults
- (optional): Maximum results (default: 10, max: 50)showArchived
- (optional): Include archived cardssortField
- (optional): Sort by field (lastModified, title, dateCreated, etc.)sortOrder
- (optional): Sort direction (asc/desc)query
- (optional): Advanced Guru Query Language query
- Returns: Cards with metadata, preview content, and collection info
#### guru-read-card
Read complete content of a specific Guru card
- Parameters:
- cardId (required): UUID of the Guru card
- Returns: Full card content with HTML formatting and metadata
#### guru-get-card-attachments
List and download attachments from Guru cards
- Parameters:
- cardId (required): UUID of the Guru carddownloadFirst
- (optional): Download first attachment content
- Returns: Attachment URLs and optional content preview
#### list-database-pages
Advanced query and search documentation pages in Notion database
- Parameters:
- limit (optional): Max pages to return (default: 10, max: 100)search
- (optional): Search page titles and descriptionscategory
- (optional): Filter by exact category matchtags
- (optional): Filter by tags (OR logic) - ["flutter", "testing"]status
- (optional): Filter by status (published, draft, archived, review)sortBy
- (optional): Sort by field (title, last_edited, created, category, status)sortOrder
- (optional): Sort direction (ascending, descending)startCursor
- (optional): Pagination cursor for next page
- Returns: Filtered pages with rich metadata, active filter indicators, and pagination info
- Use case: AI agents finding relevant docs based on current context
#### create-page-from-markdown
Create new Notion documentation pages from markdown content or files
- Parameters:
- markdown (optional): Raw markdown content to convertfilePath
- (optional): Path to local markdown file (relative to docs/)pageTitle
- (optional): Page title (auto-extracted from markdown if not provided)metadata
- (optional): Page metadata object:category
- (optional): Page category for organizationtags
- (optional): Array of tags for discovery - ["react", "hooks", "performance"]description
- (optional): Searchable page descriptionstatus
- (optional): Publication status (published, draft, review)
- Returns: Created page details with statistics
- Features: Converts markdown to Notion blocks, sets proper metadata, unlimited category/tag creation
#### update-page
Update existing Notion page content and/or metadata
- Parameters:
- pageId (required): Notion page ID to updatemarkdown
- (optional): New markdown content (replaces all content)filePath
- (optional): Path to markdown file for content replacementcategory
- (optional): Update page categorytags
- (optional): Replace all page tagsdescription
- (optional): Update page description
- Returns: Update confirmation with statistics
- Note: Content updates create new page and archive old one for history preservation
#### archive-page
Archive (soft delete) Notion pages by moving to trash
- Parameters:
- pageId (required): Notion page ID to archive
- Returns: Archive confirmation
- Note: Cannot be undone via API
#### export-page-to-markdown
Export Notion pages to clean markdown format
- Parameters:
- pageId (required): Notion page ID to exportsaveToFile
- (optional): Absolute file path to save markdown
- Returns: Markdown content with conversion statistics
- Features: Converts all Notion blocks back to standard markdown
#### hello
Example tool demonstrating MCP capabilities with usage guide
The server automatically detects the environment:
- Development Mode: NODE_ENV=development + DEV_HOME set
- Production Mode: Default when environment variables not set
#### Development Setup
`bashSet environment variables for development
export NODE_ENV=development
export DEV_HOME="/path/to/your/mcp_server"
$3
`json
{
"mcpServers": {
"ai-docs-dev": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"NODE_ENV": "development",
"DEV_HOME": "/Users/yourusername/path/to/mcp_server",
"GURU_TOKEN": "your-username:your-token"
}
}
}
}
`Getting Guru credentials:
1. Log into Guru โ Settings โ API Access
2. Generate API token
3. Format as
username:token (e.g., john.doe@company.com:abc123def456)$3
`json
{
"mcpServers": {
"ai-docs-dev": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"NODE_ENV": "development",
"DEV_HOME": "/Users/yourusername/path/to/mcp_server",
"NOTION_TOKEN": "your-notion-integration-token",
"NOTION_MCP_DATABASE_ID": "your-database-id"
}
}
}
}
`Setting up Notion integration:
1. Go to Notion Integrations
2. Create new integration โ Get API key
3. Create or share a database with your integration
4. Copy database ID from URL:
https://notion.so/{database_id}?v=...๐ Documentation Structure
Local documentation is organized in this structure:
`
docs/
โโโ code_guidelines/
โ โโโ flutter/
โ โ โโโ architecture/
โ โ โ โโโ flutter_best_practices.md
โ โ โ โโโ flutter_riverpod_clean_architecture.md
โ โ โ โโโ freezed_guide.md
โ โ โโโ riverpod_testing_guide.md
โ โโโ react/
โ โ โโโ react_best_practices.md
โ โโโ nestjs/
โ โ โโโ nestjs_best_practices.md
โ โโโ git/
โ โโโ graphite_commands_reference.md
โโโ service-docs/
โโโ notion-api-guide.md
โโโ notion-formatting-reference.md
โโโ guru-api-integration-guide.md
โโโ mcp-inspector-testing-guide.md
`๐ Installation & Usage
$3
`bash
Clone and install dependencies
git clone
cd mcp_server
npm installDevelopment mode (with hot reload)
npm run devBuild for production
npm run buildStart production server
npm start
`$3
#### Development Configuration
`json
{
"mcpServers": {
"ai-docs-dev": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"NODE_ENV": "development",
"DEV_HOME": "/Users/yourusername/code/personal/ai-docs/mcp_server",
"GURU_TOKEN": "your-username:your-api-token",
"NOTION_TOKEN": "your-notion-integration-token",
"NOTION_MCP_DATABASE_ID": "your-database-id"
}
}
}
}
`#### Production Configuration
`json
{
"mcpServers": {
"ai-docs": {
"command": "npx",
"args": ["ai-docs-mcp-server"],
"env": {
"GURU_TOKEN": "your-username:your-api-token",
"NOTION_TOKEN": "your-notion-integration-token",
"NOTION_MCP_DATABASE_ID": "your-database-id"
}
}
}
}
`Note: Place
mcp-config.json in your Claude Desktop settings directory.๐งช Testing & Development
$3
Comprehensive testing support using MCP Inspector:
`bash
Interactive UI testing
npm run inspectCLI mode testing
npm run inspect:cliList all available tools
npm run inspect:cli:toolsRun comprehensive test suite
npm run test:inspectorBasic server validation
npm run validate
`$3
`bash
Test local documentation listing
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call \
--tool-name legacy-list-docsTest reading local documentation
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call \
--tool-name legacy-read-doc \
--tool-arg category="service-docs" \
--tool-arg name="notion-api-guide"
`$3
`bash
Test database page querying
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call \
--tool-name list-database-pages \
--tool-arg search="testing" \
--tool-arg limit=5Test page creation
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call \
--tool-name create-page-from-markdown \
--tool-arg markdown="# Test Page\n\nThis is a test." \
--tool-arg pageTitle="Test Page"
`$3
`bash
Test Guru card search
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call \
--tool-name guru-list-cards \
--tool-arg searchTerms="API documentation" \
--tool-arg maxResults=5Test reading specific card
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call \
--tool-name guru-read-card \
--tool-arg cardId="your-card-uuid-here"
`๐ง How It Works
$3
1. Server Initialization: Creates MCP server with stdio transport
2. Service Registration: Initializes Notion and Guru services
3. Tool Registration: Registers all 11 tools with proper validation schemas
4. Request Handling: Processes tool calls via JSON-RPC over stdio
5. Content Processing: Handles markdown โ Notion conversion, API calls, and file operations
6. Response Delivery: Returns formatted content with comprehensive error handling
$3
- ๐ ๏ธ Tool-First Architecture: All functionality through well-defined, documented tools
- ๐ Multi-Platform Integration: Local docs + Guru + Notion in one server
- ๐ Advanced Query System: Powerful filtering, sorting, and search across all platforms
- ๐ Markdown โ Notion Conversion: Seamless content transformation with proper formatting
- ๐ท๏ธ Unlimited Categorization: Create any categories, tags, and status values dynamically
- ๐ Rich Metadata Support: Comprehensive metadata handling across all platforms
- ๐ Secure Configuration: Environment-based credential handling
- ๐จ Robust Error Handling: Graceful degradation with helpful error messages
- ๐ Development Support: Hot reload, inspection tools, and comprehensive testing
- ๐ Bi-directional Sync: Import and export content between platforms
๐ก Usage Patterns
$3
`bash
Discover available documentation
legacy-list-docs()Read specific documentation with fuzzy matching
legacy-read-doc(category="code_guidelines/flutter", name="best-practices")
`$3
`bash
Find documentation by context
list-database-pages(search="testing", tags=["react", "automation"], status="published")Create documentation from markdown
create-page-from-markdown(
markdown="# API Guide\n\nComplete API documentation...",
metadata={
category: "api-reference",
tags: ["api", "rest", "authentication"],
description: "Complete REST API documentation",
status: "published"
}
)Export for backup or migration
export-page-to-markdown(pageId="page-uuid", saveToFile="/path/to/backup.md")
`$3
`bash
Search institutional knowledge
guru-list-cards(searchTerms="kubernetes troubleshooting", maxResults=10)Read detailed procedures
guru-read-card(cardId="05f199c3-0096-458d-a4df-464d55192690")Access visual guides and attachments
guru-get-card-attachments(cardId="card-uuid", downloadFirst=true)
`๐๏ธ Build Process
The automated build process:
1. TypeScript Compilation: Compiles all source files to JavaScript
2. Documentation Copying: Copies
docs/ directory to dist/docs/
3. Executable Setup: Makes the main script executable
4. Type Generation: Generates TypeScript declarations
5. Validation: Ensures all imports and dependencies are correctBuild outputs:
-
dist/index.js - Main executable
- dist/docs/ - Local documentation files
- dist/*/.js - Compiled modules
- dist/*/.d.ts - TypeScript declarations๐ Requirements
- Node.js: โฅ20.0.0 (for latest async/await and ESM support)
- MCP SDK: v1.12.0 (automatically installed)
- Operating System: Cross-platform (macOS, Linux, Windows)
$3
- Local Documentation: Markdown files in
docs/ directory structure
- Guru Access: Valid Guru API credentials for knowledge base functionality
- Notion Access: Notion integration token and database ID for Notion functionality๐ Security Notes
- ๐ Environment Variables: All credentials handled securely through environment variables
- ๐ซ No Token Storage: No credentials stored in code or logs
- โก API Rate Limits: Automatic handling of API rate limiting
- ๐ File Access: Local file access restricted to docs directory only
- ๐ Input Validation: All parameters validated with Zod schemas
๐ What's New
$3
- ๐ Complete Notion Database Management: 5 new powerful Notion tools
- ๐ Advanced Query System: Search, filter, sort by category, tags, status, dates
- ๐ Markdown โ Notion Conversion: Seamless bi-directional content transformation
- ๐ท๏ธ Unlimited Categorization: Dynamic creation of categories, tags, and status values
- ๐ Rich Metadata Support: Categories, tags, descriptions, status tracking
- ๐ Pagination Support: Handle large datasets with cursor-based pagination
- โก Performance Optimizations: Efficient database queries and content processing
- ๐ ๏ธ Development Mode: Enhanced development experience with proper environment handling
$3
- ๐ Improved File Discovery: Better path resolution for development and production
- ๐ Fuzzy Matching: Find files even with approximate names
- ๐๏ธ Development Support: Proper development mode with
DEV_HOME` environment variable- ๐ง Full Guru API Integration: Complete knowledge base access
- ๐ Advanced Search: Powerful search and filtering across Guru cards
- ๐ Attachment Support: Access and download card attachments
- ๐ท๏ธ Metadata Rich: Complete card metadata and collection information
MIT License - See package.json for details.
---
This MCP server transforms static documentation, institutional knowledge, and content management into an intelligent, queryable ecosystem for AI assistants. It enables context-aware development guidance, comprehensive documentation management, and seamless access to your organization's collective knowledge across multiple platforms through a unified, powerful API.