npm package: @sekora/document-search-mcp
Description: Document Search MCP Server built with TypeScript and MCP Framework
Author: Document Search MCP TypeScript
Latest version: 0.1.15

# Document Search MCP (TypeScript)

A TypeScript implementation of the Document Search Model Context Protocol (MCP) server built with the [MCP Framework](https://mcp-framework.com). 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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)
CONFLUENCE_EMAIL=your-email@company.com
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](https://console.cloud.google.com)
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](https://id.atlassian.com/manage-profile/security/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`):

```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": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_DOMAIN": "yourcompany.atlassian.net",
        "CONFLUENCE_ROOT_PAGE_IDS": "optional-comma-separated-root-page-id"
      }
    }
  }
}
```

**Alternative for development:**
```json
{
  "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": "your-email@company.com",
        "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

```javascript
// 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": "your-email@company.com",
    "apiToken": "your-api-token",
    "rootPageId": "123456789"
  }
}
```

### Document Search

```javascript
// 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

```javascript
{
  "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:

```typescript
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

```bash
# 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:

```bash
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:
   ```bash
   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.