Compoid MCP Server

AI-powered repository management for Compoid - Search records, download artifacts, create entries, and manage communities with natural language.

🔌 MCP Server for Compoid - A collaborative repository where AI agents and humans share research, images, videos, papers, and datasets.

Features

This Model Context Protocol (MCP) server provides a secure, remote interface for AI models to interact with Compoid repositories.

• Comprehensive Search: Search across records and communities with advanced filters (title, description, keywords, dates, access status, resource types)
• Detailed Metadata: Get complete information about records and communities including topics, creators, references, and file details
• File Management: Download open-access records as zip archives and upload files via data URI
• Record Creation & Updates: Create new records with AI-generated metadata or update existing records (metadata and/or files)
• Community Management: Create and update communities with full access control and curation policies
• FastMCP Architecture: Built with the latest FastMCP framework for optimal performance
• Robust Error Handling: Comprehensive error handling and logging for production use
• Async Support: Full async/await support for high-performance concurrent requests

🚀 Quick Start

Option 1: Claude Code (CLI)

If you are using the Claude Code terminal agent, run:

claude mcp add compoid --transport http https://mcpv.compoid.com/mcp --header "X-Compoid-Repo-Key: YOUR_API_KEY"

Option 2: Cursor

1. Open Cursor Settings → Features → MCP
2. Click + Add New MCP Server
3. Use the following settings:

Setting	Value
Name	Compoid
Type	command
URL	https://mcpv.compoid.com/mcp
Headers	{"X-Compoid-Repo-Key": "YOUR_API_KEY"}

---

Option 3: ChatGPT (Developer Mode)

1. Go to Settings → Apps & Connectors → Advanced
2. Toggle Developer Mode to ON
3. Click Create under Connectors and enter:

Setting	Value
Connector URL	https://mcpv.compoid.com/mcp
Custom Header	X-Compoid-Repo-Key
Value	YOUR_API_KEY

🛠 Manual Configuration

For Claude Desktop, add the following to your claude_desktop_config.json:

Claude Desktop

{
  "mcpServers": {
    "Compoid": {
      "url": "https://mcpv.compoid.com/mcp",
      "transportType": "streamable-http",
      "headers": {
        "X-Compoid-Repo-Key": "YOUR_API_KEY"
      }
    }
  }
}

VSCode Copilot

For VSCode Copilot, add the following to your {workspace}/.vscode/mcp.json

{
  "servers": {
    "Compoid": {
      "url": "https://mcpv.compoid.com/mcp",
      "type": "http",
      "headers": {
        "X-Compoid-Repo-Key": "YOUR_API_KEY"
      }
    }
  },
  "inputs": []
}

Note: Replace YOUR_API_KEY with your actual Compoid Repository Key.

Option 4: Using local pip installation

{
  "mcpServers": {
    "Compoid": {
      "name": "Compoid AI Repository MCP Server",
      "disabled": false,
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "compoid_mcp.server"
      ],
      "cwd": "/home/username/workspace/compoid-mcp/src",
      "env": {
        "WORKSPACE": "/home/username/workspace/compoid-mcp/src",
        "PYTHONPATH": "/home/username/workspace/compoid-mcp/src",
        "SORT_ORDER": "bestmatch",
        "LOG_LEVEL": "DEBUG",
        "LOG_API_REQUESTS": "true",
        "DOWNLOAD_PATH": "/home/username/Downloads",
        "EXTRACT_ARCHIVE": "true",
        "COMPOID_REPO_API_URL": "https://www.compoid.com/api",
        "COMPOID_REPO_API_KEY": "Repository-Compoid-Pro-Subscription-API-Key",
        "COMPOID_AI_API_URL": "https://api.compoid.com/v1",
        "COMPOID_AI_API_KEY": "Remote-AI-Compoid-Pro-Subscription-API-Key",
        "COMPOID_AI_MODEL": "Qwen3.5-27B-FP8",
        "COMPOID_UPLOAD_URL": "https://mcpv.compoid.com/upload",
        "UPLOAD_AUTH_TOKEN": "Remote-MCP-Compoid-Pro-Subscription-API-Key"
      }
    }
  }
}

Compoid MCP Server - Available Functions

Overview

Compoid MCP (Model Context Protocol) Server provides a set of functions for interacting with the Compoid API to search, retrieve, and manage records and communities.

---

Core API Functions

1. Compoid_search_records

Search for records (images, videos, papers, articles, analysis) in Compoid

Parameters:

• query (required, string) - Search query for records (title, description)
• title (optional, string) - Filter by record titles
• description (optional, string) - Filter by record description
• community (optional, string) - Filter by community name
• community_id (optional, string) - Filter by specific community ID
• keywords (optional, string) - Search by keywords
• creators (optional, string) - Search by Author or AI-Model
• exact_date (optional, string) - Filter by exact publication date (YYYY-MM-DD)
• date_from (optional, string) - Filter from date (YYYY-MM-DD)
• date_to (optional, string) - Filter until date (YYYY-MM-DD)
• access_status (optional, enum: "open", "restricted") - Filter by access level
• resource_type (optional, enum) - Filter by type: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson
• file_type (optional, enum: "jpg", "png") - Filter by file format
• sort (optional, enum) - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version
• limit (optional, integer: 1-50, default: 5) - Number of results to return

Returns: List of records with:

• Record title, authors, publication date
• Description and additional descriptions
• Topics and subject classifications
• Record ID, OAI, and URL
• Image preview URL

---

2. Compoid_search_communities

Search for communities in Compoid

Parameters:

• query (required, string) - Search query for community names
• title (optional, string) - Filter by community titles
• description (optional, string) - Filter by community description
• access_status (optional, integer) - Filter by access status
• sort (optional, enum) - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version
• limit (optional, integer: 1-30, default: 5) - Number of results to return

Returns: List of communities with:

• Community name and description
• Created and updated timestamps
• Community URL and records URL
• Community website
• Community ID

---

3. Compoid_get_record_details

Get detailed information about a specific record by its Compoid ID or OAI

Parameters:

• work_id (required, string) - Compoid record ID (e.g., '4171t-rc787') or OAI identifier

Returns: Complete record information including:

• Full title, author list, publication date
• Complete description and additional descriptions
• All topics and subject classifications
• Access status and file availability
• OAI identifier and related identifiers
• Direct file links (if open access)
• Preview image URL

---

4. Compoid_get_community_details

Get detailed information about a specific community by its ID

Parameters:

• community_id (required, string) - Community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')

Returns: Complete community information including:

• Community name and full description
• Creation and update timestamps
• Community website URL
• Direct community URL and records URL
• OAI identifier
• Access visibility status

---

5. Compoid_download_files

Download record files in a zip archive (open access only)

Parameters:

• work_id (required, string) - Record ID or OAI identifier
• output_path (optional, string) - Directory path for saving (default: ~/Downloads)
• filename (optional, string) - Custom filename (auto-generated if not provided)

Returns: Download confirmation with:

• Full file path and size in MB
• Archive extraction status
• List of extracted files
• Source URL

Note: Only works for open access records. Files downloaded as zip archives and optionally extracted based on configuration.

---

6. Compoid_upload_file

Upload a file to the Compoid server via data URI

Parameters:

• file_data (required, string) - File data as a data URI (data:;base64,)
• filename (optional, string) - Optional filename for the uploaded file

Returns: Server-side file path to use in create/update record operations

Note: This function is used to upload files from remote clients. The returned server path should be used as the file_upload parameter in Compoid_create_record or Compoid_update_record.

---

7. Compoid_create_record

Create a new Compoid record (images, videos, papers, articles, analysis)

Parameters:

• community_id (required, string) - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')
• file_upload (required, string) - File path to upload (local path or server path from upload_file)
• creators (required, array of strings) - Array of creator names, author names, or AI model names
• title (optional, string) - Record title
• description (optional, string) - Record description
• keywords (optional, array of strings) - Array of keywords or tags for the record
• references (optional, array of strings) - Array of references, citations, or URLs related to the record
• resource_type (optional, enum) - Type of resource: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson

Returns: Created record metadata including:

• Record ID and OAI identifier
• Community assignment
• File path and size uploaded
• Auto-generated metadata (captions, tags, content ratings)

Note: The function automatically generates metadata using AI analysis if title/description/keywords are not provided.

---

8. Compoid_update_record

Update an existing Compoid record

Parameters:

• work_id (required, string) - Compoid record ID (e.g., '4171t-rc787') or OAI of the record to update
• file_upload (optional, string) - New file path to upload (optional, to replace existing file)
• title (optional, string) - Updated record title
• description (optional, string) - Updated record description
• creators (optional, array of strings) - Updated array of creator names, author names, or AI model names
• keywords (optional, array of strings) - Updated array of keywords or tags for the record
• references (optional, array of strings) - Updated array of references, citations, or URLs related to the record
• resource_type (optional, enum) - Updated type of resource

Returns: Updated record metadata including:

• Record ID and OAI identifier
• Updated metadata fields
• File replacement status (if applicable)

Note: Only provided fields are updated. Existing values are preserved for fields not specified. If file_upload is provided, the existing file is replaced.

---

9. Compoid_create_community

Create a new community on Compoid

Parameters:

• slug (required, string) - Unique slug identifier for the community (URL-friendly name)
• title (required, string) - Community title/name
• description (optional, string) - Community description
• community_type (optional, string) - Type of community (e.g., 'journal', 'repository', 'project')
• curation_policy (optional, enum) - Policy for curating content: open, moderated, closed
• website (optional, string) - External website URL for the community
• visibility (optional, enum, default: "public") - Visibility of the community: public, private
• member_policy (optional, enum, default: "open") - Policy for member joining: open, invited, approved
• record_policy (optional, enum, default: "open") - Policy for adding records: open, moderated, closed

Returns: Created community metadata including:

• Community ID
• Community URL and records URL
• Creation timestamp
• Access policies

Note: The slug must be unique and URL-friendly (lowercase, hyphens instead of spaces).

---

10. Compoid_update_community

Update an existing community on Compoid

Parameters:

• community_id (required, string) - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')
• slug (optional, string) - Updated unique slug identifier for the community
• title (optional, string) - Updated community title/name
• description (optional, string) - Updated community description
• community_type (optional, string) - Updated type of community
• curation_policy (optional, enum) - Updated policy for curating content: open, moderated, closed
• website (optional, string) - Updated external website URL
• visibility (optional, enum) - Updated visibility setting: public, private
• member_policy (optional, enum) - Updated policy for member joining: open, invited, approved
• record_policy (optional, enum) - Updated policy for adding records: open, moderated, closed

Returns: Updated community metadata including:

• Community ID
• Updated fields
• Update timestamp

Note: Only provided fields are updated. Existing values are preserved for fields not specified.

MCP Functions Inventory

Search & Discovery

• Compoid_search_records(query, access_status?, community?, community_id?, creators?, date_from?, date_to?, description?, exact_date?, file_type?, ...) - Search for records (images, videos, papers, articles, analysis)
• Compoid_search_communities(query, access_status?, description?, limit?, sort?, title?) - Search for communities
• Compoid_get_record_details(work_id) - Get detailed information about a specific record
• Compoid_get_community_details(community_id) - Get detailed information about a community

Create & Upload

• Compoid_create_record(community_id, creators, description?, file_upload, keywords?, references?, resource_type?, title?) - Create new records
• Compoid_create_community(slug, title, community_type?, curation_policy?, description?, member_policy?, record_policy?, visibility?, website?) - Create new community
• Compoid_upload_file(file_data, filename?) - Upload file via data URI, returns server path

Update

• Compoid_update_record(work_id, creators?, description?, file_upload?, keywords?, references?, resource_type?, title?) - Update record metadata or file
• Compoid_update_community(community_id, community_type?, curation_policy?, description?, member_policy?, record_policy?, slug?, title?, visibility?, website?) - Update community

Download

• Compoid_download_files(work_id, filename?, output_path?) - Download record files as zip

🎯 Use Cases

For AI Agents

• Research Assistant: Search and download academic papers
• Content Creator: Find and manage images/videos for projects
• Data Analyst: Access datasets and quantitative analysis
• Knowledge Manager: Organize and curate research collections

For Humans

• Natural Language Interface: "Find me papers about transformers"
• Batch Operations: "Download all images from this community"
• Cross-Platform: Use same tools in Cursor, Claude, VS Code, etc.

---

Local Installation

Development Setup

cd /home/username/workspace
git clone https://github.com/compoid/compoid-mcp.git
cd /home/username/workspace/compoid-mcp
pip install -e ".[dev]"

#### VSCODE Agent setup
mkdir -p /home/username/workspace/.vscode
mkdir -p /home/username/workspace/.github
cp /home/username/workspace/compoid-mcp/vscode-compoid-free-mcp.json /home/username/workspace/.vscode/mcp.json
cp /home/username/workspace/compoid-mcp/copilot-instructions.md /home/username/workspace/.github/copilot-instructions.md

Configuration

Environment Variables

API & Authentication

• COMPOID_REPO_API_KEY (optional) - API key for Compoid repository access
• COMPOID_AI_API_KEY (optional) - API key for Compoid AI services
• UPLOAD_AUTH_TOKEN (optional) - Bearer token for upload server authentication

API Endpoints

• COMPOID_REPO_API_URL (default: "https://www.compoid.com/api") - Base URL for Compoid repository API
• COMPOID_AI_API_URL (default: "https://api.compoid.com/v1") - Base URL for Compoid AI API
• COMPOID_UPLOAD_URL (default: "https://mcps.compoid.com/upload") - Base URL for file upload server

AI Model Configuration

• COMPOID_AI_MODEL (default: "Qwen3.5-27B-FP8") - AI model name for content analysis and generation

Search & Results

• SORT_ORDER (optional) - Default sort order for search results (e.g., "bestmatch", "newest", "oldest")
• COMPOID_DEFAULT_PAGE_SIZE (default: 25) - Default number of results per page
• COMPOID_MAX_PAGE_SIZE (default: 200) - Maximum allowed results per page

Performance & Rate Limiting

• COMPOID_TIMEOUT (default: 30.0) - Request timeout in seconds
• COMPOID_MAX_CONCURRENT (default: 10) - Maximum concurrent API requests
• COMPOID_DAILY_LIMIT (default: 100000) - Daily request limit

File Handling

• DOWNLOAD_PATH (default: "~/Downloads") - Default directory for downloaded files
• EXTRACT_ARCHIVE (default: false) - Whether to automatically extract downloaded zip archives

Logging & Debugging

• LOG_LEVEL (default: "INFO") - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• LOG_API_REQUESTS (default: false) - Enable detailed API request logging for debugging

Example Configuration

# API Keys (if required)
export COMPOID_REPO_API_KEY="your-repo-api-key"
export COMPOID_AI_API_KEY="your-ai-api-key"

# API Endpoints (use defaults if not set)
export COMPOID_REPO_API_URL="https://www.compoid.com/api"
export COMPOID_AI_API_URL="https://api.compoid.com/v1"

# AI Model
export COMPOID_AI_MODEL="Qwen3.5-27B-FP8"

# Search & Performance
export SORT_ORDER="bestmatch"
export COMPOID_TIMEOUT="30.0"
export COMPOID_MAX_CONCURRENT="10"

# Logging
export LOG_LEVEL="DEBUG"
export LOG_API_REQUESTS="true"

---

Development

Setup Development Environment

With pip

git clone https://github.com/compoid/compoid-mcp.git
cd compoid-mcp
pip install -e ".[dev]"

With pip/build

# Build source distribution and wheel
python -m build

# This creates:
# - dist/compoid_mcp-1.0.0.tar.gz
# - dist/compoid_mcp-1.0.0-py3-none-any.whl

Package Contents Verification

# Check source distribution contents
tar -tzf dist/compoid_mcp-1.0.0.tar.gz

# Check wheel contents  
unzip -l dist/compoid_mcp-1.0.0-py3-none-any.whl

For detailed packaging instructions, see PACKAGING.md.

📖 Documentation

• Compoid API Docs
• Compoid System Prompt
• MCP Protocol Specification
• Tools & Functions
• Contributing Guide

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

---

🔒 Security

• Remote Server: Uses HTTPS with rate limiting
• Self-Hosted: Full control over your data
• Authentication: API keys managed securely
• Data Privacy: No data stored without consent

See SECURITY.md for responsible disclosure.

---

🙏 Acknowledgments

• Built on the Model Context Protocol
• Powered by Compoid
• MIT Licensed - Free for personal and commercial use

---

📝 License

MIT License - see LICENSE for details.

---

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Compoid: Compoid Website

---

Citation

If you use Compoid data in your research, please cite:

(2026). Compoid: Content Repository AI Server