Document Search MCP (TypeScript)

A TypeScript implementation of the Document Search Model Context Protocol (MCP) server built with the MCP Framework. This server enables AI assistants like Claude Desktop to search and retrieve documents from multiple sources, including Google Drive and Confluence wiki integration.

Features

• 🔍 Multi-source document search - Search across Google Drive documents and Confluence wiki pages
• 🔐 Multi-auth support - OAuth 2.0 for Google Drive, API tokens for Confluence
• 📄 Full content retrieval - Get complete document content for analysis
• 🏗️ Modular TypeScript architecture - Clean separation using MCP Framework patterns
• ⚡ Type-safe development - Full TypeScript support with Zod validation
• 🔌 Extensible design - Ready framework for additional connectors
• ☁️ Cloud deployment ready - Deployable to various cloud platforms

Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• Google OAuth 2.0 credentials (for Google Drive integration)
• Confluence API token (for wiki integration)

Installation

# Install directly via npm
npx @sekora/document-search-mcp

# Or clone for development
git clone https://gitlab.com/sekora-ai/document-search-mcp.git
cd document-search-mcp
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your credentials:
# - Google OAuth from: https://console.cloud.google.com
# - Confluence API token from: https://id.atlassian.com/manage-profile/security/api-tokens

Development

# Build the project
npm run build

# Run in development mode (with hot reload)
npm run dev

# Type checking
npm run type-check

# Linting
npm run lint
npm run lint:fix

# Run tests
npm test
npm run test:coverage

Production

# Build and run
npm run build
npm start

# Or run directly as MCP server
node dist/index.js

Configuration

Environment Variables

Create a .env file in the project root:

# Google OAuth 2.0 Credentials (required for Google Drive)
GOOGLE_CLIENT_ID=your-google-client-id-here
GOOGLE_CLIENT_SECRET=your-google-client-secret-here

# Optional: Restrict search to specific Google Drive folders
# GOOGLE_DRIVE_FOLDER_IDS=1abc123def456,2xyz789ghi012

# Confluence API Credentials (required for wiki integration)
[email protected]
CONFLUENCE_API_TOKEN=your-atlassian-api-token
CONFLUENCE_DOMAIN=yourcompany.atlassian.net

# Optional: Start search from specific Confluence pages
# CONFLUENCE_ROOT_PAGE_IDS=123456789

# Optional settings
LOG_LEVEL=INFO

Authentication Setup

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Drive API
4. In "Credentials" → "Create Credentials":
   • Choose "OAuth Client ID" (not API key or Service Account)
   • Select "Desktop Application" as the application type
   • Set redirect URI to http://localhost
5. Copy the Client ID and Client Secret to your .env file

Confluence API Setup

1. Go to Atlassian API tokens
2. Create a new API token
3. Add your email, API token, and Confluence domain to your .env file
4. Optionally specify a root page ID to limit searches to that page hierarchy

Claude Desktop Integration

Add to your Claude Desktop configuration (~/.claude/mcp_servers.json):

{
  "mcpServers": {
    "document-search": {
      "command": "npx",
      "args": ["@sekora/document-search-mcp@latest"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_DRIVE_FOLDER_IDS": "optional-comma-separated-folder-ids",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_DOMAIN": "yourcompany.atlassian.net",
        "CONFLUENCE_ROOT_PAGE_IDS": "optional-comma-separated-root-page-id"
      }
    }
  }
}

Alternative for development:

{
  "mcpServers": {
    "document-search-dev": {
      "command": "node",
      "args": ["/path/to/document-search-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_DOMAIN": "yourcompany.atlassian.net"
      }
    }
  }
}

MCP Tools

The server provides these MCP tools:

Setup Tools

• setup_google_drive - OAuth setup and configuration wizard for Google Drive
• setup_confluence - API token setup and configuration for Confluence

Search Tools (available after setup)

• search_documents - Search across connected document sources
• get_document_content - Retrieve full content from specific documents
• list_sources - Show configured document sources and connection status

Usage Examples

Initial Setup

// First-time setup
{
  "tool": "setup_google_drive",
  "arguments": {
    "step": "start"
  }
}

// Complete setup after authorization
{
  "tool": "setup_google_drive", 
  "arguments": {
    "step": "complete",
    "redirectUrl": "http://localhost/?code=...",
    "folderUrls": ["https://drive.google.com/drive/folders/your-folder-id"]
  }
}

// Setup Confluence
{
  "tool": "setup_confluence",
  "arguments": {
    "domain": "yourcompany.atlassian.net",
    "email": "[email protected]",
    "apiToken": "your-api-token",
    "rootPageId": "123456789"
  }
}

Document Search

// Basic search
{
  "tool": "search_documents",
  "arguments": {
    "query": "quarterly report 2024"
  }
}

// Advanced search with filters
{
  "tool": "search_documents",
  "arguments": {
    "query": "budget analysis",
    "maxResults": 20,
    "filters": {
      "googleDrive": {
        "folderIds": ["folder-id-1", "folder-id-2"],
        "mimeTypes": ["application/vnd.google-apps.document"]
      },
      "confluence": {
        "spaceKeys": ["SPACE1", "SPACE2"],
        "pageTypes": ["page"]
      }
    }
  }
}

Get Document Content

{
  "tool": "get_document_content",
  "arguments": {
    "documentId": "document-id-from-search",
    "source": "google_drive",
    "includeMetadata": true,
    "format": "text"
  }
}

Architecture

Core Components

• MCP Framework Server - Built using mcp-framework for TypeScript
• Search Orchestrator - Coordinates searches across multiple connectors
• Document Connectors - Modular interfaces for document sources
• Type System - Comprehensive Zod schemas for type safety
• Configuration Manager - Handles setup and credentials management

Project Structure

src/
├── index.ts                 # Server entry point
├── search-orchestrator.ts   # Multi-source search coordination
├── types/                   # TypeScript type definitions
│   ├── document.ts          # Document models and schemas
│   ├── search.ts            # Search query and result types
│   └── config.ts            # Configuration schemas
├── connectors/              # Document source connectors
│   ├── base-connector.ts    # Abstract base connector
│   ├── google-drive-connector.ts # Google Drive implementation
│   └── confluence-connector.ts   # Confluence implementation
├── tools/                   # MCP tool implementations
│   ├── search-documents.ts  
│   ├── get-document-content.ts
│   ├── list-sources.ts
│   ├── setup-google-drive.ts
│   └── setup-confluence.ts
└── config/                  # Configuration management
    └── config-manager.ts

Type Safety

The project uses comprehensive Zod schemas for:

• Document models and metadata
• Search queries and filters
• Configuration validation
• MCP tool input/output schemas

Supported Document Sources

• ✅ Google Drive - Google Docs, Sheets, Slides, and various file formats with OAuth 2.0
• ✅ Confluence - Wiki pages and documentation with API token authentication
• 🚧 SharePoint - Planned
• 🚧 Other sources - Framework ready for extension

Deployment

Cloud Deployment

The Document Search MCP server can be deployed to various cloud platforms:

Available deployment options:

• Local: Run directly with Node.js
• Container: Docker deployment to any container platform
• Serverless: Deploy to AWS Lambda, Google Cloud Functions, or similar
• Traditional hosting: VPS, dedicated servers

Environment Configuration: Set environment variables according to your deployment platform:

• Google Drive: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_DRIVE_FOLDER_IDS
• Confluence: CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_DOMAIN

Development

Adding New Connectors

Create a new connector by extending the base class:

import { BaseConnector } from './connectors/base-connector.js';
import { Document, DocumentMatch } from './types/document.js';
import { SearchQuery } from './types/search.js';

export class MySourceConnector extends BaseConnector {
  readonly sourceType = 'my_source';

  protected async setupAuthentication(): Promise<void> {
    // Implement authentication setup
  }

  protected async validateConnection(): Promise<void> {
    // Implement connection validation
  }

  async searchDocuments(query: SearchQuery): Promise<DocumentMatch[]> {
    // Implement search functionality
    return [];
  }

  async getDocument(documentId: string): Promise<Document> {
    // Implement single document retrieval
    throw new Error('Not implemented');
  }

  async listDocuments(options?: Record<string, any>): Promise<Document[]> {
    // Implement document listing
    return [];
  }
}

Code Quality

# Run full quality checks
npm run type-check
npm run lint
npm test

# Auto-fix formatting issues  
npm run lint:fix

Differences from Python Version

This TypeScript implementation provides several improvements:

1. Type Safety - Full TypeScript support with Zod validation
2. MCP Framework - Built using the modern MCP Framework instead of raw SDK
3. Modular Architecture - Clear separation of concerns with dependency injection
4. Modern JavaScript - ES2022+ features, async/await throughout
5. Better Error Handling - Comprehensive error handling with proper typing
6. Enhanced Configuration - Type-safe configuration management
7. Development Experience - Hot reload, comprehensive linting, testing setup

Configuration Storage

• Config file: ~/.config/document-search-mcp/config.yaml
• OAuth tokens: ~/.config/document-search-mcp/token.json
• Setup: Automatic directory creation during first setup

Troubleshooting

Common Issues

1. Google Drive OAuth Setup Failed

   • Ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set
   • Check that Google Drive API is enabled in your Google Cloud project
   • Verify you selected "OAuth Client ID" → "Desktop Application" when creating credentials
   • Ensure redirect URI is set to http://localhost in your OAuth configuration

2. Confluence Connection Issues

   • Verify your CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, and CONFLUENCE_DOMAIN are correct
   • Test your API token at: https://id.atlassian.com/manage-profile/security/api-tokens
   • Ensure your domain format is correct (e.g., company.atlassian.net, not https://company.atlassian.net/)
   • Check that you have appropriate permissions to access Confluence pages

3. MCP Server Connection Issues

   • If using Claude Code and the server disconnects early, ensure you're using the latest version
   • Try restarting Claude Desktop after configuration changes
   • Check logs in Claude Desktop for specific error messages

4. Build Errors

   • Run npm run type-check to identify TypeScript errors
   • Ensure you're using Node.js 18.0.0 or higher

5. Search/Connection Issues

   • Check that your OAuth token hasn't expired (re-run setup if needed)
   • Verify network connectivity to Google Drive API
   • Run list_sources tool to check connector status
   • If using folder restrictions, verify folder IDs are correct

Debug Mode

Enable debug logging:

LOG_LEVEL=DEBUG npm start

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the full test suite:

   npm run type-check && npm run lint && npm test

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please use the project's issue tracker.