SourceSync.ai MCP Server

A Model Context Protocol (MCP) server implementation for the SourceSync.ai API. This server allows AI models to interact with SourceSync.ai's knowledge management platform through a standardized interface.

Features

• Manage namespaces for organizing knowledge
• Ingest content from various sources (text, URLs, websites, external services)
• Retrieve, update, and manage documents stored in your knowledge base
• Perform semantic and hybrid searches against your knowledge base
• Access document content directly from parsed text URLs
• Manage connections to external services
• Default configuration support for seamless AI integration

Installation

Running with npx

# Install and run with your API key and tenant ID
env SOURCESYNC_API_KEY=your_api_key npx -y sourcesyncai-mcp

Installing via Smithery

To install sourcesyncai-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @pbteja1998/sourcesyncai-mcp --client claude

Manual Installation

# Clone the repository
git clone https://github.com/yourusername/sourcesyncai-mcp.git
cd sourcesyncai-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
node dist/index.js

Running on Cursor

To configure SourceSync.ai MCP in Cursor:

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click + Add New MCP Server
4. Enter the following:
   • Name: sourcesyncai-mcp (or your preferred name)
   • Type: command
   • Command: env SOURCESYNCAI_API_KEY=your-api-key npx -y sourcesyncai-mcp

After adding, you can use SourceSync.ai tools with Cursor's AI features by describing your knowledge management needs.

Running on Windsurf

Add this to your ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "sourcesyncai-mcp": {
      "command": "npx",
      "args": ["-y", "soucesyncai-mcp"],
      "env": {
        "SOURCESYNC_API_KEY": "your_api_key",
        "SOURCESYNC_NAMESPACE_ID": "your_namespace_id",
        "SOURCESYNC_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Running on Claude Desktop

To use this MCP server with Claude Desktop:

1. Locate the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Edit the configuration file to add the SourceSync.ai MCP server:

{
  "mcpServers": {
    "sourcesyncai-mcp": {
      "command": "npx",
      "args": ["-y", "sourcesyncai-mcp"],
      "env": {
        "SOURCESYNC_API_KEY": "your_api_key",
        "SOURCESYNC_NAMESPACE_ID": "your_namespace_id",
        "SOURCESYNC_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

1. Save the configuration file and restart Claude Desktop

Configuration

Environment Variables

Required

• SOURCESYNC_API_KEY: Your SourceSync.ai API key (required)

Optional

• SOURCESYNC_NAMESPACE_ID: Default namespace ID to use for operations
• SOURCESYNC_TENANT_ID: Your tenant ID (optional)

Configuration Examples

Basic configuration with default values:

export SOURCESYNC_API_KEY=your_api_key
export SOURCESYNC_TENANT_ID=your_tenant_id
export SOURCESYNC_NAMESPACE_ID=your_namespace_id

Available Tools

Authentication

• validate_api_key: Validate a SourceSync.ai API key

{
  "name": "validate_api_key",
  "arguments": {}
}

Namespaces

• create_namespace: Create a new namespace
• list_namespaces: List all namespaces
• get_namespace: Get details of a specific namespace
• update_namespace: Update a namespace
• delete_namespace: Delete a namespace

{
  "name": "create_namespace",
  "arguments": {
    "name": "my-namespace",
    "fileStorageConfig": {
      "provider": "S3_COMPATIBLE",
      "config": {
        "endpoint": "s3.amazonaws.com",
        "accessKey": "your_access_key",
        "secretKey": "your_secret_key",
        "bucket": "your_bucket",
        "region": "us-east-1"
      }
    },
    "vectorStorageConfig": {
      "provider": "PINECONE",
      "config": {
        "apiKey": "your_pinecone_api_key",
        "environment": "your_environment",
        "index": "your_index"
      }
    },
    "embeddingModelConfig": {
      "provider": "OPENAI",
      "config": {
        "apiKey": "your_openai_api_key",
        "model": "text-embedding-3-small"
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "list_namespaces",
  "arguments": {
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "get_namespace",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "update_namespace",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX",
    "name": "updated-namespace-name"
  }
}

{
  "name": "delete_namespace",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX"
  }
}

Data Ingestion

• ingest_text: Ingest text content
• ingest_urls: Ingest content from URLs
• ingest_sitemap: Ingest content from a sitemap
• ingest_website: Ingest content from a website
• ingest_notion: Ingest content from Notion
• ingest_google_drive: Ingest content from Google Drive
• ingest_dropbox: Ingest content from Dropbox
• ingest_onedrive: Ingest content from OneDrive
• ingest_box: Ingest content from Box
• get_ingest_job_run_status: Get the status of an ingestion job run

{
  "name": "ingest_text",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "TEXT",
      "config": {
        "name": "example-document",
        "text": "This is an example document for ingestion.",
        "metadata": {
          "category": "example",
          "author": "AI Assistant"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_urls",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "URLS",
      "config": {
        "urls": ["https://example.com/page1", "https://example.com/page2"],
        "metadata": {
          "source": "web",
          "category": "documentation"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_sitemap",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "SITEMAP",
      "config": {
        "url": "https://example.com/sitemap.xml",
        "metadata": {
          "source": "sitemap",
          "website": "example.com"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_website",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "WEBSITE",
      "config": {
        "url": "https://example.com",
        "maxDepth": 3,
        "maxPages": 100,
        "metadata": {
          "source": "website",
          "domain": "example.com"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_notion",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "NOTION",
      "config": {
        "connectionId": "your_notion_connection_id",
        "metadata": {
          "source": "notion",
          "workspace": "My Workspace"
        }
      }
    },
    "tenantId": "your_tenant_id"
  }
}

{
  "name": "ingest_google_drive",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "GOOGLE_DRIVE",
      "config": {
        "connectionId": "connection_XXX",
        "metadata": {
          "source": "google_drive",
          "owner": "user@example.com"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_dropbox",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "DROPBOX",
      "config": {
        "connectionId": "connection_XXX",
        "metadata": {
          "source": "dropbox",
          "account": "user@example.com"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_onedrive",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "ONEDRIVE",
      "config": {
        "connectionId": "connection_XXX",
        "metadata": {
          "source": "onedrive",
          "account": "user@example.com"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "ingest_box",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestConfig": {
      "source": "BOX",
      "config": {
        "connectionId": "connection_XXX",
        "metadata": {
          "source": "box",
          "owner": "user@example.com"
        }
      }
    },
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "get_ingest_job_run_status",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "ingestJobRunId": "ingest_job_run_XXX",
    "tenantId": "tenant_XXX"
  }
}

Documents

• getDocuments: Retrieve documents with optional filters
• updateDocuments: Update document metadata
• deleteDocuments: Delete documents
• resyncDocuments: Resync documents
• fetchUrlContent: Fetch text content from document URLs

{
  "name": "getDocuments",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX",
    "filterConfig": {
      "documentTypes": ["PDF"]
    },
    "includeConfig": {
      "parsedTextFileUrl": true
    }
  }
}

{
  "name": "updateDocuments",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX",
    "documentIds": ["doc_XXX", "doc_YYY"],
    "filterConfig": {
      "documentIds": ["doc_XXX", "doc_YYY"]
    },
    "data": {
      "metadata": {
        "status": "reviewed",
        "category": "technical"
      }
    }
  }
}

{
  "name": "deleteDocuments",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX",
    "documentIds": ["doc_XXX", "doc_YYY"],
    "filterConfig": {
      "documentIds": ["doc_XXX", "doc_YYY"]
    }
  }
}

{
  "name": "resyncDocuments",
  "arguments": {
    "namespaceId": "namespace_XXX",
    "tenantId": "tenant_XXX",
    "documentIds": ["doc_XXX", "doc_YYY"],
    "filterConfig": {
      "documentIds": ["doc_XXX", "doc_YYY"]
    }
  }
}

{
  "name": "fetchUrlContent",
  "arguments": {
    "url": "https://api.sourcesync.ai/v1/documents/doc_XXX/content?format=text",
    "apiKey": "your_api_key",
    "tenantId": "tenant_XXX"
  }
}

Search

• semantic_search: Perform semantic search
• hybrid_search: Perform hybrid search (semantic + keyword)

{
  "name": "semantic_search",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "query": "example document",
    "topK": 5,
    "tenantId": "tenant_XXX"
  }
}

{
  "name": "hybrid_search",
  "arguments": {
    "namespaceId": "your_namespace_id",
    "query": "example document",
    "topK": 5,
    "tenantId": "tenant_XXX",
    "hybridConfig": {
      "semanticWeight": 0.7,
      "keywordWeight": 0.3
    }
  }
}

Connections

• create_connection: Create a new connection to an external service
• list_connections: List all connections
• get_connection: Get details of a specific connection
• update_connection: Update a connection
• revoke_connection: Revoke a connection

{
  "name": "create_connection",
  "arguments": {
    "tenantId": "tenant_XXX",
    "namespaceId": "namespace_XXX",
    "name": "My Connection",
    "connector": "GOOGLE_DRIVE",
    "clientRedirectUrl": "https://your-app.com/callback"
  }
}

{
  "name": "list_connections",
  "arguments": {
    "tenantId": "tenant_XXX",
    "namespaceId": "namespace_XXX"
  }
}

{
  "name": "get_connection",
  "arguments": {
    "tenantId": "tenant_XXX",
    "namespaceId": "namespace_XXX",
    "connectionId": "connection_XXX"
  }
}

{
  "name": "update_connection",
  "arguments": {
    "tenantId": "tenant_XXX",
    "namespaceId": "namespace_XXX",
    "connectionId": "connection_XXX",
    "name": "Updated Connection Name",
    "clientRedirectUrl": "https://your-app.com/updated-callback"
  }
}

{
  "name": "revoke_connection",
  "arguments": {
    "tenantId": "tenant_XXX",
    "namespaceId": "namespace_XXX",
    "connectionId": "connection_XXX"
  }
}

Example Prompts

Here are some example prompts you can use with Claude or Cursor after configuring the MCP server:

• "Search my SourceSync knowledge base for information about machine learning."
• "Ingest this article into my SourceSync knowledge base: [URL]"
• "Create a new namespace in SourceSync for my project documentation."
• "List all the documents in my SourceSync namespace."
• "Get the text content of document [document_id] from my SourceSync namespace."

Troubleshooting

Connection Issues

If you encounter issues connecting the SourceSync.ai MCP server:

1. Verify Paths: Ensure all paths in your configuration are absolute paths, not relative.

2. Check Permissions: Ensure the server file has execution permissions (chmod +x dist/index.js).

3. Enable Developer Mode: In Claude Desktop, enable Developer Mode and check the MCP Log File.

4. Test the Server: Run the server directly from the command line:

   node /path/to/sourcesyncai-mcp/dist/index.js
   

5. Restart AI Client: After making changes, completely restart Claude Desktop or Cursor.

6. Check Environment Variables: Ensure all required environment variables are correctly set.

Debug Logging

For detailed logging, add the DEBUG environment variable:

Development

Project Structure

• src/index.ts: Main entry point and server setup
• src/schemas.ts: Schema definitions for all tools
• src/sourcesync.ts: Client for interacting with SourceSync.ai API
• src/sourcesync.types.ts: TypeScript type definitions

Building and Testing

# Build the project
npm run build

# Run tests
npm test

License

MIT

Links

• SourceSync.ai Documentation
• SourceSync.ai API Reference
• Model Context Protocol

Document content retrieval workflow:

1. First, use getDocuments with includeConfig.parsedTextFileUrl: true to get documents with their content URLs
2. Extract the URL from the document response
3. Use fetchUrlContent to retrieve the actual content:

{
  "name": "fetchUrlContent",
  "arguments": {
    "url": "https://example.com"
  }
}