Document Search MCP Server built with TypeScript and MCP Framework
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.
- š 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
- Node.js 18.0.0 or higher
- Google OAuth 2.0 credentials (for Google Drive integration)
- Confluence API token (for wiki integration)
``bashInstall directly via npm
npx @sekora/document-search-mcp
$3
`bash
Build the project
npm run buildRun in development mode (with hot reload)
npm run devType checking
npm run type-checkLinting
npm run lint
npm run lint:fixRun tests
npm test
npm run test:coverage
`$3
`bash
Build and run
npm run build
npm startOr 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-hereOptional: 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.netOptional: 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 statusUsage 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_DOMAINDevelopment
$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 testAuto-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 setupTroubleshooting
$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 configuration2. 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 pages3. 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 higher5. 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
``MIT License - see LICENSE file for details
For issues and feature requests, please use the project's issue tracker.