jyrkidn/wotz-docs-mcp-server

WotzDocs MCP Server

A Laravel-based MCP (Model Context Protocol) server that provides documentation from private GitHub repositories to AI assistants.

Features

• GitHub Integration: Fetches documentation from private GitHub repositories using the GitHub REST API
• MCP Tools: Provides tools for listing packages, searching documentation, and fetching content
• MCP Resources: Serves documentation as resources with proper URIs (e.g., docs://package/path/to/file.md)
• Caching: Intelligent caching to minimize API calls to GitHub
• Easy Package Management: Simple artisan commands to add and manage documentation packages

Prerequisites

• PHP 8.1+
• Laravel 10.0+
• Composer
• GitHub Personal Access Token (for private repositories)

Installation

1. Clone and setup the project:

   composer install
   cp .env.example .env
   php artisan key:generate
   

2. Configure your environment:

   Edit .env and add your GitHub token:

   GITHUB_TOKEN=your_github_personal_access_token
   

3. Run migrations:

   php artisan migrate
   

4. Publish MCP configuration (optional):

   php artisan vendor:publish --provider="PhpMcp\Laravel\Server\McpServiceProvider" --tag="mcp-config"
   

Adding Documentation Packages

Use the mcp:add-package command to add new documentation sources:

php artisan mcp:add-package <name> <owner> <repo> [options]

Examples:

# Add a package with default settings (docs in 'docs' folder, master branch)
php artisan mcp:add-package my-package myorg my-repo

php artisan mcp:add-package codedor/filament-architect codedor filament-architect

# Specify custom documentation path and branch
php artisan mcp:add-package my-package myorg my-repo --docs-path=documentation --branch=develop

# Add with description
php artisan mcp:add-package my-package myorg my-repo --description="Core API documentation"

List all packages:

php artisan mcp:list-packages

Running the MCP Server

Development (STDIO Transport):

php artisan mcp:serve

Production (HTTP+SSE Transport):

Configure your web server to serve the Laravel application, then access:

http://your-domain.com/mcp/sse

MCP Features

Tools

• list_packages: Lists all available documentation packages
• get_package_structure: Gets the file structure of a package's documentation
• search_docs: Searches across all documentation (or specific package)
• refresh_package_docs: Forces a refresh of cached documentation

Resources

• docs://index: Main documentation index (Markdown)
• docs://packages: List of packages (JSON)
• docs://{package}/{path}: Specific documentation file

Example Usage in AI Assistant:

# List available packages
Use tool: list_packages

# Get documentation structure
Use tool: get_package_structure with packageName="my-package"

# Search documentation
Use tool: search_docs with query="authentication"

# Read specific documentation
Get resource: docs://my-package/guide/getting-started.md

Configuration

Cache Settings

Configure cache duration in .env:

MCP_DOCS_CACHE_TTL=3600  # Cache for 1 hour (in seconds)

Discovery Paths

By default, MCP elements are discovered in app/Mcp/. You can customize this in config/mcp.php.

Troubleshooting

No documentation found

• Verify the GitHub repository exists and is accessible with your token
• Check that the docs_path is correct
• Ensure your GitHub token has appropriate permissions

Cache issues

# Clear MCP discovery cache
php artisan cache:clear

# Force refresh documentation for a package
php artisan mcp:serve
# Then use the refresh_package_docs tool

Debug mode

Enable debug logging in .env:

MCP_LOGGING_ENABLED=true
LOG_LEVEL=debug

Security

• Store your GitHub token securely in .env
• Never commit .env to version control
• Use appropriate GitHub token scopes (minimum: repo for private repositories)

Advanced Usage

Custom Documentation Processors

You can extend the GitHubDocumentationService to add custom processing:

1. Create a new service extending GitHubDocumentationService
2. Override methods like fetchDocumentationContent to add custom processing
3. Bind your custom service in a service provider

Adding Non-GitHub Sources

The architecture supports multiple documentation sources:

1. Create a new service implementing the same interface
2. Update the DocumentationServer to use your service
3. Add appropriate configuration options

Run the mcp server

Run the http transport:

php artisan mcp:serve --transport=http

Add this to claude code

claude mcp add --transport sse wotz-docs-mcp http://127.0.0.1:8090/mcp/sse