@synvo_ai/mcp-server/README.md

Enterprise-grade MCP server for Synvo AI - File management and AI query capabilities for Claude Desktop, VSCode, and Cursor

# Synvo AI MCP Server

A Model Context Protocol (MCP) server that integrates with Synvo AI's API, providing file management and AI query capabilities to MCP clients like Claude Desktop, VSCode, and Cursor.

## Features

- **Upload Files**: Upload files to SynvoAI with optional memory building
- **Query AI**: Send messages to SynvoAI's AI models with conversation context
- Full TypeScript support with type definitions
- Comprehensive error handling and validation
- Configurable timeouts (60s for upload/query operations)

## Quick Start

### Installation

1. Install dependencies:
```bash
npm install
```

2. Build the project:
```bash
npm run build
```

3. Set your API key (optional, defaults to demo key):
```bash
export SYNVO_API_KEY="your-api-key-here"
```

4. Run the server:
```bash
npm start
```

## Available Tools

### 1. synvo_upload_file

Upload a file to SynvoAI with optional memory building.

**Parameters:**
- `file_path` (string, required): Path to the file to upload
- `build_memory` (boolean, optional): Whether to build memory from the file (default: true)

**Example:**
```json
{
  "file_path": "/path/to/document.pdf",
  "build_memory": true
}
```

### 2. synvo_query_ai

Query SynvoAI's AI models with a message and optional conversation context.

**Parameters:**
- `message` (string, required): The message to send to the AI
- `conversation_id` (string, optional): Conversation ID for context
- `stream` (boolean, optional): Whether to stream the response (default: false)

**Example:**
```json
{
  "message": "What is the capital of France?",
  "conversation_id": "conv_xyz789"
}
```

## Integration with MCP Clients

### Claude Desktop

Add to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "synvo": {
      "command": "node",
      "args": ["/absolute/path/to/synvo-mcp/dist/index.js"],
      "env": {
        "SYNVO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### VSCode/Cursor

Add to your MCP settings:

```json
{
  "mcp.servers": {
    "synvo": {
      "command": "node",
      "args": ["/absolute/path/to/synvo-mcp/dist/index.js"],
      "env": {
        "SYNVO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Development

### Project Structure

```
synvo-mcp/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   ├── license.ts            # License management system
│   ├── cli-activate.ts       # License activation CLI
│   ├── cli-status.ts         # License status CLI
│   └── cli-deactivate.ts     # License deactivation CLI
├── scripts/
│   ├── publish.sh            # NPM publish script (Unix)
│   └── publish.bat           # NPM publish script (Windows)
├── package.json
├── tsconfig.json
├── README.md
├── CHANGELOG.md
├── QUICK_START.md
└── LICENSE
```

### Available Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run watch` - Watch mode for development
- `npm start` - Run the compiled server
- `npm run dev` - Build and run the server

### API Endpoints

The server communicates with Synvo AI API (v1.0):

- **Upload**: `POST https://api.synvo.ai/file/upload`
  - Authentication: `X-API-Key` header
  - Format: multipart/form-data
  - Parameters: file, path, build_memory, disable_lazy_metadata

- **Query**: `POST https://api.synvo.ai/ai/query`
  - Authentication: `X-API-Key` header
  - Format: multipart/form-data
  - Parameters: payload (JSON), streaming, parent_cuid, model, agent_model

For detailed API documentation, visit: https://docs.synvo.ai/docs/1.0/synvo-api/

---

# One-Click MCP Server Installation for Claude Desktop

This section provides instructions on how to package this MCP server into a single `.mcpb` file for seamless installation in Claude Desktop.

## Prerequisites

Before you begin, ensure you have the following installed and ready:

* **Node.js and npm** : The `mcpb` command-line tool is distributed via npm. You can download Node.js [here](https://nodejs.org/).
* **A local MCP server** : You should have a functioning MCP server in a local folder on your machine.
* **Claude Desktop** : The official Claude Desktop application must be installed.

## Step-by-Step Guide

The process involves initializing a manifest, packaging your server, and installing the resulting bundle file.

### 1. Install the MCPB CLI Tool

First, install the `@anthropic-ai/mcpb` package globally using npm. This gives you access to the `mcpb` command in your terminal.

**Bash**

```
npm install -g @anthropic-ai/mcpb
```

### 2. Initialize Your Server's Manifest

Navigate to the root directory of your local MCP server project in your terminal. Run the `mcpb init` command.

**Bash**

```
cd /path/to/your/mcp-server
mcpb init
```

This command launches an interactive setup wizard that will guide you through creating a `manifest.json` file. This file contains all the necessary metadata to define and run your server as an extension.

### 3. Configure the `manifest.json`

The `mcpb init` wizard will help you configure the most critical parts of the manifest. The key fields that determine how your server runs are located in the `"mcp_config"` object within the `"server"` section:

* `"command"`: The executable to run (e.g., `python`, `node`, `./my-server-binary`).
* `"args"`: An array of string arguments to pass to the command (e.g., `["-m", "my_module.server", "--port", "3000"]`).
* `"environment"`: An object defining any environment variables your server needs to run correctly.

You can also manually edit the `manifest.json` to add more advanced configurations, such as:

* **`user_config`** : Defines settings that the user can configure from the Claude Desktop UI.
* **`compatibility`** : Specifies compatibility requirements for your extension.

 For a complete and detailed guide on all available fields and their rules, please refer to the official documentation: [MANIFEST.md](https://github.com/anthropics/mcpb/blob/main/MANIFEST.md).

### 4. Package Your Extension

Once your `manifest.json` is configured, run the `mcpb pack` command in the same directory.

**Bash**

```
mcpb pack
```

This command reads your `manifest.json`, bundles all the necessary files, and creates a distributable **`.mcpb`** file in your project directory. Now, any application that supports MCPB, like Claude Desktop, can run your local server.

### 5. Install in Claude Desktop

The final step is to install the extension in the Claude Desktop app.

1. Locate the `.mcpb` file generated in the previous step.
2. **Double-click the file** . Claude Desktop will automatically open it.
3. A dialog box will appear asking for confirmation. Click  **"Install"** .

Your local MCP server is now successfully installed as a one-click extension in Claude Desktop and will be available in the extensions menu.



## Appendix: Developer's Guide

This extension was copy from official specifications as reference to build a Desktop Extension, abbreviated as "MCPB". Please follow these steps:

1. **Read the specifications thoroughly:**

   - https://github.com/anthropics/mcpb/blob/main/README.md - MCPB architecture overview, capabilities, and integration patterns
   - https://github.com/anthropics/mcpb/blob/main/MANIFEST.md - Complete extension manifest structure and field definitions
   - https://github.com/anthropics/mcpb/tree/main/examples - Reference implementations including a "Hello World" example
2. **Create a proper extension structure:**

   - Generate a valid manifest.json following the MANIFEST.md spec
   - Implement an MCP server using @modelcontextprotocol/sdk with proper tool definitions
   - Include proper error handling and timeout management
3. **Follow best development practices:**

   - Implement proper MCP protocol communication via stdio transport
   - Structure tools with clear schemas, validation, and consistent JSON responses
   - Make use of the fact that this extension will be running locally
   - Add appropriate logging and debugging capabilities
   - Include proper documentation and setup instructions
4. **Test considerations:**

   - Validate that all tool calls return properly structured responses
   - Verify manifest loads correctly and host integration works

Generate complete, production-ready code that can be immediately tested. Focus on defensive programming, clear error messages, and following the exact
MCPB specifications to ensure compatibility with the ecosystem.