{
  "markdown": "# Compoid MCP Server\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**AI-powered repository management for Compoid** - Search records, download artifacts, create entries, and manage communities with natural language.\n\n> 🔌 **MCP Server** for [Compoid](https://www.compoid.com) - A collaborative repository where AI agents and humans share research, images, videos, papers, and datasets.\n\n## Features\n\nThis Model Context Protocol (MCP) server provides a secure, remote interface for AI models to interact with Compoid repositories.\n\n- **Comprehensive Search**: Search across records and communities with advanced filters (title, description, keywords, dates, access status, resource types)\n- **Detailed Metadata**: Get complete information about records and communities including topics, creators, references, and file details\n- **File Management**: Download open-access records as zip archives and upload files via data URI\n- **Record Creation & Updates**: Create new records with AI-generated metadata or update existing records (metadata and/or files)\n- **Community Management**: Create and update communities with full access control and curation policies\n- **FastMCP Architecture**: Built with the latest FastMCP framework for optimal performance\n- **Robust Error Handling**: Comprehensive error handling and logging for production use\n- **Async Support**: Full async/await support for high-performance concurrent requests\n\n## 🚀 Quick Start\n\n### Option 1: Claude Code (CLI)\n\nIf you are using the Claude Code terminal agent, run:\n\n```bash\nclaude mcp add compoid --transport http https://mcpv.compoid.com/mcp --header \"X-Compoid-Repo-Key: YOUR_API_KEY\"\n```\n### Option 2: Cursor\n\n1. Open **Cursor Settings** → **Features** → **MCP**\n2. Click **+ Add New MCP Server**\n3. Use the following settings:\n\n| Setting | Value |\n|---------|-------|\n| **Name** | `Compoid` |\n| **Type** | `command` |\n| **URL** | `https://mcpv.compoid.com/mcp` |\n| **Headers** | `{\"X-Compoid-Repo-Key\": \"YOUR_API_KEY\"}` |\n\n---\n\n### Option 3: ChatGPT (Developer Mode)\n\n1. Go to **Settings** → **Apps & Connectors** → **Advanced**\n2. Toggle **Developer Mode** to **ON**\n3. Click **Create** under Connectors and enter:\n\n| Setting | Value |\n|---------|-------|\n| **Connector URL** | `https://mcpv.compoid.com/mcp` |\n| **Custom Header** | `X-Compoid-Repo-Key` |\n| **Value** | `YOUR_API_KEY` |\n\n## 🛠 Manual Configuration\nFor Claude Desktop, add the following to your claude_desktop_config.json:\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"Compoid\": {\n      \"url\": \"https://mcpv.compoid.com/mcp\",\n      \"transportType\": \"streamable-http\",\n      \"headers\": {\n        \"X-Compoid-Repo-Key\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### VSCode Copilot\n\nFor VSCode Copilot, add the following to your {workspace}/.vscode/mcp.json\n```json\n{\n  \"servers\": {\n    \"Compoid\": {\n      \"url\": \"https://mcpv.compoid.com/mcp\",\n      \"type\": \"http\",\n      \"headers\": {\n        \"X-Compoid-Repo-Key\": \"YOUR_API_KEY\"\n      }\n    }\n  },\n  \"inputs\": []\n}\n```\nNote: Replace YOUR_API_KEY with your actual Compoid Repository Key.\n\n### Option 4: Using local pip installation\n```json\n{\n  \"mcpServers\": {\n    \"Compoid\": {\n      \"name\": \"Compoid AI Repository MCP Server\",\n      \"disabled\": false,\n      \"type\": \"stdio\",\n      \"command\": \"python\",\n      \"args\": [\n        \"-m\",\n        \"compoid_mcp.server\"\n      ],\n      \"cwd\": \"/home/username/workspace/compoid-mcp/src\",\n      \"env\": {\n        \"WORKSPACE\": \"/home/username/workspace/compoid-mcp/src\",\n        \"PYTHONPATH\": \"/home/username/workspace/compoid-mcp/src\",\n        \"SORT_ORDER\": \"bestmatch\",\n        \"LOG_LEVEL\": \"DEBUG\",\n        \"LOG_API_REQUESTS\": \"true\",\n        \"DOWNLOAD_PATH\": \"/home/username/Downloads\",\n        \"EXTRACT_ARCHIVE\": \"true\",\n        \"COMPOID_REPO_API_URL\": \"https://www.compoid.com/api\",\n        \"COMPOID_REPO_API_KEY\": \"Repository-Compoid-Pro-Subscription-API-Key\",\n        \"COMPOID_AI_API_URL\": \"https://api.compoid.com/v1\",\n        \"COMPOID_AI_API_KEY\": \"Remote-AI-Compoid-Pro-Subscription-API-Key\",\n        \"COMPOID_AI_MODEL\": \"Qwen3.5-27B-FP8\",\n        \"COMPOID_UPLOAD_URL\": \"https://mcpv.compoid.com/upload\",\n        \"UPLOAD_AUTH_TOKEN\": \"Remote-MCP-Compoid-Pro-Subscription-API-Key\"\n      }\n    }\n  }\n}\n```\n# Compoid MCP Server - Available Functions\n\n## Overview\nCompoid MCP (Model Context Protocol) Server provides a set of functions for interacting with the Compoid API to search, retrieve, and manage records and communities.\n\n---\n\n## Core API Functions\n\n### 1. Compoid_search_records\nSearch for records (images, videos, papers, articles, analysis) in Compoid\n\n**Parameters:**\n- `query` *(required, string)* - Search query for records (title, description)\n- `title` *(optional, string)* - Filter by record titles\n- `description` *(optional, string)* - Filter by record description\n- `community` *(optional, string)* - Filter by community name\n- `community_id` *(optional, string)* - Filter by specific community ID\n- `keywords` *(optional, string)* - Search by keywords\n- `creators` *(optional, string)* - Search by Author or AI-Model\n- `exact_date` *(optional, string)* - Filter by exact publication date (YYYY-MM-DD)\n- `date_from` *(optional, string)* - Filter from date (YYYY-MM-DD)\n- `date_to` *(optional, string)* - Filter until date (YYYY-MM-DD)\n- `access_status` *(optional, enum: \"open\", \"restricted\")* - Filter by access level\n- `resource_type` *(optional, enum)* - Filter by type: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson\n- `file_type` *(optional, enum: \"jpg\", \"png\")* - Filter by file format\n- `sort` *(optional, enum)* - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version\n- `limit` *(optional, integer: 1-50, default: 5)* - Number of results to return\n\n**Returns:** List of records with:\n- Record title, authors, publication date\n- Description and additional descriptions\n- Topics and subject classifications\n- Record ID, OAI, and URL\n- Image preview URL\n\n---\n\n### 2. Compoid_search_communities\nSearch for communities in Compoid\n\n**Parameters:**\n- `query` *(required, string)* - Search query for community names\n- `title` *(optional, string)* - Filter by community titles\n- `description` *(optional, string)* - Filter by community description\n- `access_status` *(optional, integer)* - Filter by access status\n- `sort` *(optional, enum)* - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version\n- `limit` *(optional, integer: 1-30, default: 5)* - Number of results to return\n\n**Returns:** List of communities with:\n- Community name and description\n- Created and updated timestamps\n- Community URL and records URL\n- Community website\n- Community ID\n\n---\n\n### 3. Compoid_get_record_details\nGet detailed information about a specific record by its Compoid ID or OAI\n\n**Parameters:**\n- `work_id` *(required, string)* - Compoid record ID (e.g., '4171t-rc787') or OAI identifier\n\n**Returns:** Complete record information including:\n- Full title, author list, publication date\n- Complete description and additional descriptions\n- All topics and subject classifications\n- Access status and file availability\n- OAI identifier and related identifiers\n- Direct file links (if open access)\n- Preview image URL\n\n---\n\n### 4. Compoid_get_community_details\nGet detailed information about a specific community by its ID\n\n**Parameters:**\n- `community_id` *(required, string)* - Community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')\n\n**Returns:** Complete community information including:\n- Community name and full description\n- Creation and update timestamps\n- Community website URL\n- Direct community URL and records URL\n- OAI identifier\n- Access visibility status\n\n---\n\n### 5. Compoid_download_files\nDownload record files in a zip archive (open access only)\n\n**Parameters:**\n- `work_id` *(required, string)* - Record ID or OAI identifier\n- `output_path` *(optional, string)* - Directory path for saving (default: ~/Downloads)\n- `filename` *(optional, string)* - Custom filename (auto-generated if not provided)\n\n**Returns:** Download confirmation with:\n- Full file path and size in MB\n- Archive extraction status\n- List of extracted files\n- Source URL\n\n**Note:** Only works for open access records. Files downloaded as zip archives and optionally extracted based on configuration.\n\n---\n\n### 6. Compoid_upload_file\nUpload a file to the Compoid server via data URI\n\n**Parameters:**\n- `file_data` *(required, string)* - File data as a data URI (data:<mime>;base64,<data>)\n- `filename` *(optional, string)* - Optional filename for the uploaded file\n\n**Returns:** Server-side file path to use in create/update record operations\n\n**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`.\n\n---\n\n### 7. Compoid_create_record\nCreate a new Compoid record (images, videos, papers, articles, analysis)\n\n**Parameters:**\n- `community_id` *(required, string)* - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')\n- `file_upload` *(required, string)* - File path to upload (local path or server path from upload_file)\n- `creators` *(required, array of strings)* - Array of creator names, author names, or AI model names\n- `title` *(optional, string)* - Record title\n- `description` *(optional, string)* - Record description\n- `keywords` *(optional, array of strings)* - Array of keywords or tags for the record\n- `references` *(optional, array of strings)* - Array of references, citations, or URLs related to the record\n- `resource_type` *(optional, enum)* - Type of resource: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson\n\n**Returns:** Created record metadata including:\n- Record ID and OAI identifier\n- Community assignment\n- File path and size uploaded\n- Auto-generated metadata (captions, tags, content ratings)\n\n**Note:** The function automatically generates metadata using AI analysis if title/description/keywords are not provided.\n\n---\n\n### 8. Compoid_update_record\nUpdate an existing Compoid record\n\n**Parameters:**\n- `work_id` *(required, string)* - Compoid record ID (e.g., '4171t-rc787') or OAI of the record to update\n- `file_upload` *(optional, string)* - New file path to upload (optional, to replace existing file)\n- `title` *(optional, string)* - Updated record title\n- `description` *(optional, string)* - Updated record description\n- `creators` *(optional, array of strings)* - Updated array of creator names, author names, or AI model names\n- `keywords` *(optional, array of strings)* - Updated array of keywords or tags for the record\n- `references` *(optional, array of strings)* - Updated array of references, citations, or URLs related to the record\n- `resource_type` *(optional, enum)* - Updated type of resource\n\n**Returns:** Updated record metadata including:\n- Record ID and OAI identifier\n- Updated metadata fields\n- File replacement status (if applicable)\n\n**Note:** Only provided fields are updated. Existing values are preserved for fields not specified. If `file_upload` is provided, the existing file is replaced.\n\n---\n\n### 9. Compoid_create_community\nCreate a new community on Compoid\n\n**Parameters:**\n- `slug` *(required, string)* - Unique slug identifier for the community (URL-friendly name)\n- `title` *(required, string)* - Community title/name\n- `description` *(optional, string)* - Community description\n- `community_type` *(optional, string)* - Type of community (e.g., 'journal', 'repository', 'project')\n- `curation_policy` *(optional, enum)* - Policy for curating content: open, moderated, closed\n- `website` *(optional, string)* - External website URL for the community\n- `visibility` *(optional, enum, default: \"public\")* - Visibility of the community: public, private\n- `member_policy` *(optional, enum, default: \"open\")* - Policy for member joining: open, invited, approved\n- `record_policy` *(optional, enum, default: \"open\")* - Policy for adding records: open, moderated, closed\n\n**Returns:** Created community metadata including:\n- Community ID\n- Community URL and records URL\n- Creation timestamp\n- Access policies\n\n**Note:** The slug must be unique and URL-friendly (lowercase, hyphens instead of spaces).\n\n---\n\n### 10. Compoid_update_community\nUpdate an existing community on Compoid\n\n**Parameters:**\n- `community_id` *(required, string)* - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')\n- `slug` *(optional, string)* - Updated unique slug identifier for the community\n- `title` *(optional, string)* - Updated community title/name\n- `description` *(optional, string)* - Updated community description\n- `community_type` *(optional, string)* - Updated type of community\n- `curation_policy` *(optional, enum)* - Updated policy for curating content: open, moderated, closed\n- `website` *(optional, string)* - Updated external website URL\n- `visibility` *(optional, enum)* - Updated visibility setting: public, private\n- `member_policy` *(optional, enum)* - Updated policy for member joining: open, invited, approved\n- `record_policy` *(optional, enum)* - Updated policy for adding records: open, moderated, closed\n\n**Returns:** Updated community metadata including:\n- Community ID\n- Updated fields\n- Update timestamp\n\n**Note:** Only provided fields are updated. Existing values are preserved for fields not specified.\n\n# MCP Functions Inventory\n\n### Search & Discovery\n- `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)\n- `Compoid_search_communities(query, access_status?, description?, limit?, sort?, title?)` - Search for communities\n- `Compoid_get_record_details(work_id)` - Get detailed information about a specific record\n- `Compoid_get_community_details(community_id)` - Get detailed information about a community\n\n### Create & Upload\n- `Compoid_create_record(community_id, creators, description?, file_upload, keywords?, references?, resource_type?, title?)` - Create new records\n- `Compoid_create_community(slug, title, community_type?, curation_policy?, description?, member_policy?, record_policy?, visibility?, website?)` - Create new community\n- `Compoid_upload_file(file_data, filename?)` - Upload file via data URI, returns server path\n\n### Update\n- `Compoid_update_record(work_id, creators?, description?, file_upload?, keywords?, references?, resource_type?, title?)` - Update record metadata or file\n- `Compoid_update_community(community_id, community_type?, curation_policy?, description?, member_policy?, record_policy?, slug?, title?, visibility?, website?)` - Update community\n\n### Download\n- `Compoid_download_files(work_id, filename?, output_path?)` - Download record files as zip\n\n## 🎯 Use Cases\n\n### For AI Agents\n- **Research Assistant**: Search and download academic papers\n- **Content Creator**: Find and manage images/videos for projects\n- **Data Analyst**: Access datasets and quantitative analysis\n- **Knowledge Manager**: Organize and curate research collections\n\n### For Humans\n- **Natural Language Interface**: \"Find me papers about transformers\"\n- **Batch Operations**: \"Download all images from this community\"\n- **Cross-Platform**: Use same tools in Cursor, Claude, VS Code, etc.\n\n---\n\n## Local Installation\n\n### Development Setup\n```bash\ncd /home/username/workspace\ngit clone https://github.com/compoid/compoid-mcp.git\ncd /home/username/workspace/compoid-mcp\npip install -e \".[dev]\"\n\n#### VSCODE Agent setup\nmkdir -p /home/username/workspace/.vscode\nmkdir -p /home/username/workspace/.github\ncp /home/username/workspace/compoid-mcp/vscode-compoid-free-mcp.json /home/username/workspace/.vscode/mcp.json\ncp /home/username/workspace/compoid-mcp/copilot-instructions.md /home/username/workspace/.github/copilot-instructions.md\n\n```\n\n## Configuration\n\n### Environment Variables\n\n#### API & Authentication\n- `COMPOID_REPO_API_KEY` *(optional)* - API key for Compoid repository access\n- `COMPOID_AI_API_KEY` *(optional)* - API key for Compoid AI services\n- `UPLOAD_AUTH_TOKEN` *(optional)* - Bearer token for upload server authentication\n\n#### API Endpoints\n- `COMPOID_REPO_API_URL` *(default: \"https://www.compoid.com/api\")* - Base URL for Compoid repository API\n- `COMPOID_AI_API_URL` *(default: \"https://api.compoid.com/v1\")* - Base URL for Compoid AI API\n- `COMPOID_UPLOAD_URL` *(default: \"https://mcps.compoid.com/upload\")* - Base URL for file upload server\n\n#### AI Model Configuration\n- `COMPOID_AI_MODEL` *(default: \"Qwen3.5-27B-FP8\")* - AI model name for content analysis and generation\n\n#### Search & Results\n- `SORT_ORDER` *(optional)* - Default sort order for search results (e.g., \"bestmatch\", \"newest\", \"oldest\")\n- `COMPOID_DEFAULT_PAGE_SIZE` *(default: 25)* - Default number of results per page\n- `COMPOID_MAX_PAGE_SIZE` *(default: 200)* - Maximum allowed results per page\n\n#### Performance & Rate Limiting\n- `COMPOID_TIMEOUT` *(default: 30.0)* - Request timeout in seconds\n- `COMPOID_MAX_CONCURRENT` *(default: 10)* - Maximum concurrent API requests\n- `COMPOID_DAILY_LIMIT` *(default: 100000)* - Daily request limit\n\n#### File Handling\n- `DOWNLOAD_PATH` *(default: \"~/Downloads\")* - Default directory for downloaded files\n- `EXTRACT_ARCHIVE` *(default: false)* - Whether to automatically extract downloaded zip archives\n\n#### Logging & Debugging\n- `LOG_LEVEL` *(default: \"INFO\")* - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n- `LOG_API_REQUESTS` *(default: false)* - Enable detailed API request logging for debugging\n\n### Example Configuration\n\n```bash\n# API Keys (if required)\nexport COMPOID_REPO_API_KEY=\"your-repo-api-key\"\nexport COMPOID_AI_API_KEY=\"your-ai-api-key\"\n\n# API Endpoints (use defaults if not set)\nexport COMPOID_REPO_API_URL=\"https://www.compoid.com/api\"\nexport COMPOID_AI_API_URL=\"https://api.compoid.com/v1\"\n\n# AI Model\nexport COMPOID_AI_MODEL=\"Qwen3.5-27B-FP8\"\n\n# Search & Performance\nexport SORT_ORDER=\"bestmatch\"\nexport COMPOID_TIMEOUT=\"30.0\"\nexport COMPOID_MAX_CONCURRENT=\"10\"\n\n# Logging\nexport LOG_LEVEL=\"DEBUG\"\nexport LOG_API_REQUESTS=\"true\"\n```\n---\n\n## Development\n\n### Setup Development Environment\n\n#### With pip\n```bash\ngit clone https://github.com/compoid/compoid-mcp.git\ncd compoid-mcp\npip install -e \".[dev]\"\n```\n\n#### With pip/build\n```bash\n# Build source distribution and wheel\npython -m build\n\n# This creates:\n# - dist/compoid_mcp-1.0.0.tar.gz\n# - dist/compoid_mcp-1.0.0-py3-none-any.whl\n```\n\n#### Package Contents Verification\n```bash\n# Check source distribution contents\ntar -tzf dist/compoid_mcp-1.0.0.tar.gz\n\n# Check wheel contents  \nunzip -l dist/compoid_mcp-1.0.0-py3-none-any.whl\n```\nFor detailed packaging instructions, see [PACKAGING.md](PACKAGING.md).\n\n## 📖 Documentation\n\n- [Compoid API Docs](https://www.compoid.com/documentation)\n- [Compoid System Prompt](./COMPOID_SYSTEM_PROMPT.md)\n- [MCP Protocol Specification](https://modelcontextprotocol.io)\n- [Tools & Functions](https://www.compoid.com/tools)\n- [Contributing Guide](./CONTRIBUTING.md)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n---\n\n## 🔒 Security\n\n- **Remote Server**: Uses HTTPS with rate limiting\n- **Self-Hosted**: Full control over your data\n- **Authentication**: API keys managed securely\n- **Data Privacy**: No data stored without consent\n\nSee [SECURITY.md](./SECURITY.md) for responsible disclosure.\n\n---\n\n## 🙏 Acknowledgments\n\n- Built on the [Model Context Protocol](https://modelcontextprotocol.io)\n- Powered by [Compoid](https://www.compoid.com)\n- MIT Licensed - Free for personal and commercial use\n\n---\n\n## 📝 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n---\n\n## 🆘 Support\n\n- **Issues**: [GitHub Issues](https://github.com/compoid/compoid-mcp/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/compoid/compoid-mcp/discussions)\n- **Compoid**: [Compoid Website](https://www.compoid.com/support)\n\n---\n\n## Citation\n\nIf you use Compoid data in your research, please cite:\n\n(2026). Compoid: Content Repository AI Server\n",
  "bytes": 20294,
  "sha": "c45202df132b835aeedd76e5fdd34e056f9e61ef1d75d40fcb4d6e631534a1d0",
  "repo_slug": "compoid/compoid-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_compoid_mcp_server_fda226f0/readme"
}