DocsHub MCP Server (FastMCP)

A production-grade Model Context Protocol (MCP) server for DocsHub, built with FastMCP and running on Vercel.

Features

• FastMCP Framework: Built on FastMCP v3.8.5 for robust MCP implementation
• OAuth 2.0 + PKCE: Secure authentication with full PKCE support
• RS256 JWT: Industry-standard token signing with key rotation
• Document Management: Full CRUD operations for documents and folders
• Search: Advanced document search capabilities
• OpenTelemetry: Comprehensive observability and tracing
• TypeScript: Fully typed for better developer experience
• Vercel Deployment: Serverless deployment with global edge network

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   MCP Server    │────▶│  DocsHub API    │
│ (Claude, etc.)  │ SSE │   (FastMCP)     │HTTP │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │                          │
                               ▼                          ▼
                        ┌─────────────┐          ┌─────────────┐
                        │  Supabase   │          │   Storage   │
                        │  (Tokens)   │          │ (Documents) │
                        └─────────────┘          └─────────────┘

Quick Start

Prerequisites

• Node.js >=20 <23
• npm 10.8.1+
• Supabase project
• Vercel account

Installation

# Clone the repository
git clone https://github.com/docshub/docshub-mcp-fastmcp.git
cd docshub-mcp-fastmcp

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Configure your .env file with actual values

Development

# Run development server
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

Deployment

# Deploy to Vercel
vercel

# Deploy to production
vercel --prod

Configuration

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | SUPABASE_URL | Supabase project URL | Yes | | SUPABASE_SERVICE_ROLE_KEY | Supabase service role key | Yes | | JWT_SECRET | Secret for JWT signing (min 32 chars) | Yes | | DOCSHUB_API_URL | DocsHub API endpoint | Yes | | DOCSHUB_APP_URL | DocsHub app URL | Yes | | OAUTH_CLIENT_ID | OAuth client ID | Yes | | OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry endpoint | No |

MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) with:

{
  "mcpServers": {
    "docshub": {
      "command": "npx",
      "args": ["-y", "@docshub/mcp@latest"]
    }
  }
}

Available Tools

Document Management

• list_documents - List all documents with optional folder filtering
• get_document - Get a specific document by ID
• create_document - Create a new document
• update_document - Update document title/content
• delete_document - Delete a document
• search_documents - Search documents by query

Folder Management

• list_folders - List folders with hierarchy
• create_folder - Create a new folder
• update_folder - Update folder properties
• delete_folder - Delete a folder
• move_folder - Move folder to new location

OAuth Flow

1. MCP client initiates OAuth with /oauth/authorize
2. User is redirected to DocsHub for authentication
3. DocsHub redirects back with authorization code
4. Client exchanges code for tokens at /oauth/token
5. Tokens are used for all subsequent API calls
6. Refresh tokens enable automatic renewal

Security

• PKCE: Full PKCE implementation for OAuth security
• RS256 JWT: Asymmetric key signing with rotation
• Token Expiry: Access tokens expire in 1 hour
• Refresh Rotation: Refresh tokens rotate on use
• CORS: Configured for secure cross-origin requests
• RLS: Row-level security on all database tables

Monitoring

The server includes OpenTelemetry instrumentation for:

• Request latency tracking
• Error rate monitoring
• Tool execution metrics
• OAuth flow tracing

Metrics are exported to your configured OTLP endpoint.

Development

Project Structure

src/
├── index.ts          # Main server entrypoint
├── auth/
│   ├── oauth.ts      # OAuth provider implementation
│   └── jwt.ts        # JWT token handling
├── tools/
│   ├── documents.ts  # Document management tools
│   ├── folders.ts    # Folder management tools
│   └── index.ts      # Tool exports
├── config/
│   └── index.ts      # Configuration management
└── utils/
    ├── supabase.ts   # Database client
    └── tracing.ts    # OpenTelemetry setup

Testing

# Unit tests
npm test

# Coverage report
npm run test:coverage

# E2E tests
npm run test:e2e

Adding New Tools

1. Create tool in src/tools/
2. Define Zod schema for parameters
3. Implement with tracing
4. Export from src/tools/index.ts
5. Add tests

Troubleshooting

Common Issues

1. OAuth errors: Check redirect URIs match exactly
2. Token expiry: Implement refresh token flow
3. SSE disconnects: Client should auto-reconnect
4. CORS issues: Verify allowed origins

Debug Mode

Enable debug logging:

ENABLE_DEBUG_LOGS=true npm run dev

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit pull request

License

MIT License - see LICENSE file for details

Support

• Documentation: https://docshub.app/docs/mcp
• Issues: https://github.com/docshub/docshub-mcp-fastmcp/issues
• Email: [email protected]

Server Endpoint

The MCP server is deployed at: https://mcp.docshub.app