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

$3

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

$3

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

`

$3

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

$3

`bash


Build and run

npm run build
npm start

Or run directly as MCP server

node dist/index.js
`

Configuration

$3

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
`

$3

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

$3

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:

$3


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

$3

- 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

$3

`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"
}
}
`

$3

`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"]
}
}
}
}
`

$3

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

Architecture

$3

- 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

$3

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

$3

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

$3

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

$3

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 {
// Implement authentication setup
}

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

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

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

async listDocuments(options?: Record): Promise {
// Implement document listing
return [];
}
}
`

$3

`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

$3

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

$3

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.