@docshub/mcp

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

• MCP client initiates OAuth with /oauth/authorize
• User is redirected to DocsHub for authentication
• DocsHub redirects back with authorization code
• Client exchanges code for tokens at /oauth/token
• Tokens are used for all subsequent API calls
• 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

• Create tool in src/tools/
• Define Zod schema for parameters
• Implement with tracing
• Export from src/tools/index.ts
• Add tests

Troubleshooting

Common Issues

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

Debug Mode

Enable debug logging:

ENABLE_DEBUG_LOGS=true npm run dev

Contributing

• Fork the repository
• Create feature branch
• Add tests for new features
• Ensure all tests pass
• 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: [e-mail]

Server Endpoint

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