# Copus MCP Server

An MCP (Model Context Protocol) server that allows AI assistants to search and retrieve human-curated content recommendations from [Copus](https://copus.network).

## What is Copus?

**Copus** is a human-curated content discovery platform — "The Internet Treasure Map". Unlike SEO-driven search results, Copus surfaces recommendations from real people who explain *why* content is valuable.

Each curation includes:
- **Curator's personal note** — Why they recommend this
- **Curator credentials** — Why they're qualified to recommend this
- **Original source URL** — The actual content being recommended
- **AI-enhanced metadata** — Key takeaways, target audience, problem solved
- **Engagement metrics** — Views, saves, comments from the community

## What This MCP Server Enables

This server gives AI assistants access to Copus's curated content database. Instead of generic search results, your AI can find:
- Tools and resources vetted by domain experts
- Articles recommended by practitioners in the field
- Hidden gems that real people found valuable enough to share

## Compatible AI Platforms

This MCP server works with any AI platform that supports the Model Context Protocol:

- **Claude Desktop** (Anthropic)
- **Claude Code** (Anthropic)
- **Cursor** (AI code editor)
- **Cline** (VS Code extension)
- **Continue** (VS Code/JetBrains extension)
- **Zed** (Code editor)
- Any other MCP-compatible AI platform

## Installation

### Quick Start (npx)

No installation required — run directly with npx:

```bash
npx copus-mcp-server
```

### Global Installation

```bash
npm install -g copus-mcp-server
```

Then run:

```bash
copus-mcp-server
```

### Local Installation

```bash
npm install copus-mcp-server
```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "copus": {
      "command": "npx",
      "args": ["copus-mcp-server"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "copus": {
      "command": "copus-mcp-server"
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "copus": {
      "command": "npx",
      "args": ["copus-mcp-server"]
    }
  }
}
```

### Cursor

Add to your Cursor MCP configuration (`.cursor/mcp.json` in your project or global settings):

```json
{
  "mcpServers": {
    "copus": {
      "command": "npx",
      "args": ["copus-mcp-server"]
    }
  }
}
```

### Cline (VS Code Extension)

Add to Cline's MCP settings in VS Code:

1. Open VS Code Settings
2. Search for "Cline MCP"
3. Add the server configuration:

```json
{
  "copus": {
    "command": "npx",
    "args": ["copus-mcp-server"]
  }
}
```

### Continue (VS Code/JetBrains)

Add to your Continue configuration (`~/.continue/config.json`):

```json
{
  "mcpServers": [
    {
      "name": "copus",
      "command": "npx",
      "args": ["copus-mcp-server"]
    }
  ]
}
```

## Available Tools

### `search_curations`

Search human-curated content recommendations on Copus.

**Parameters:**
- `query` (string, required): Search keywords
- `limit` (number, optional): Maximum results (default: 10, max: 50)

**Returns:** Array of curations with:
- Title and description
- Curator name and profile
- Original source URL
- Category and keywords
- Engagement metrics (views, saves)

### `get_curation`

Get detailed information about a specific curation.

**Parameters:**
- `id` (string, required): Curation ID (UUID from search results)

**Returns:** Full curation details including:
- Curator's personal recommendation note
- Curator credentials
- Key takeaways
- Target audience
- What problem this content solves
- Full engagement metrics

## Example Use Cases

Once configured, you can ask your AI assistant things like:

### Learning Resources
> "I want to learn Python, what resources should I check out?"
>
> "Find me some recommended machine learning tutorials"
>
> "What are the best resources for learning web development?"

### Tools & Software
> "What tools do designers recommend for wireframing?"
>
> "Find me some AI tools that people actually use and recommend"
>
> "What's a good free video editing software?"

### Reading & Content
> "Any good reads on creative writing?"
>
> "Find me articles about productivity that people found valuable"
>
> "What are some recommended newsletters about tech?"

### Specific Topics
> "Find watermark remover tools"
>
> "What Linux tools do people recommend?"
>
> "Show me personal growth content recommendations"

## Example Response

When you search for "python tutorials", you might get:

```json
{
  "query": "python tutorials",
  "totalResults": 5,
  "results": [
    {
      "id": "abc123...",
      "title": "Real Python - Python Tutorials",
      "description": "Comprehensive Python tutorials covering basics to advanced topics...",
      "originalSource": "https://realpython.com",
      "category": "Technology",
      "curator": "experienced_dev",
      "engagement": {
        "views": 150,
        "saves": 23
      }
    }
  ]
}
```

## Why Use Copus Over Regular Search?

| Regular Search | Copus Curations |
|----------------|-----------------|
| SEO-optimized results | Human-selected recommendations |
| Algorithm-driven | Expert-vetted content |
| No context on quality | Curator explains why it's valuable |
| Anonymous sources | Known curator with credentials |
| Quantity-focused | Quality-focused |

## Development

### Building from Source

```bash
git clone https://github.com/copus-io/copus-mcp-server.git
cd copus-mcp-server
npm install
npm run build
```

### Running in Development

```bash
npm run dev
```

### Testing

```bash
# Run the server
npm start

# In another terminal, test with MCP inspector or your AI platform
```

## API Reference

This MCP server wraps the Copus public API:

- **Search API:** `https://copus.network/api/search?q={query}`
- **Curation Details:** `https://copus.network/work/{id}?format=json`
- **OpenAPI Spec:** `https://copus.network/.well-known/openapi.yaml`
- **AI Plugin Manifest:** `https://copus.network/.well-known/ai-plugin.json`

## Links

- **Copus Website:** https://copus.network
- **Browse Topics:** https://copus.network/topics
- **All Articles:** https://copus.network/articles.txt
- **MCP Protocol:** https://modelcontextprotocol.io
- **MCP TypeScript SDK:** https://github.com/modelcontextprotocol/typescript-sdk

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- **Issues:** https://github.com/copus-io/copus-mcp-server/issues
- **Copus:** https://copus.network

---

Built with love by the [Copus](https://copus.network) team.