npm package: @improvedigital/publisher-mcp-server
Description: MCP Server for publisher inventory management in the Improve Digital Platform
Latest version: 1.0.0

# ImproveDigital Publisher MCP Server

A Model Context Protocol (MCP) server implementation that provides access to ImproveDigital API for inventory management.
The server handles OAuth authentication and exports tools to list, create and update publisher inventory. Tools are
dynamically generated from a curated version of the API Swagger document.

## 🏗️ Architecture

```
┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
│   MCP Client    │    │    MCP Server        │    │   API Providers     │
│                 │    │                      │    │                     │
│ • Tool Calls    │◄──►│ • Service Registry   │◄──►│ • ImproveDigital    │
│ • List Tools    │    │ • Dynamic Tools      │    │ • Swagger Docs      │  
│ • Sessions      │    │ • Schema Resolution  │    │ • OAuth Tokens      │
│                 │    │ • Authentication     │    │                     │
└─────────────────┘    └──────────────────────┘    └─────────────────────┘
                                │
                                ▼
                       ┌──────────────────────┐
                       │   Generated Tools    │
                       │                      │
                       │ • Dynamic Schemas    │
                       │ • Parameter Mapping  │
                       │ • Request Routing    │
                       │ • Response Handling  │
                       └──────────────────────┘
```

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ 
- npm or yarn

### Installation

1. **Clone and install dependencies:**
```bash
git clone <repository-url>
cd improvedigital-publisher-mcp-server
npm install
```

2. **Configure environment variables:**
```bash
cp .env.example .env
```

Edit `.env` with your API credentials:
```env
# ImproveDigital API Configuration
IMPROVE_DIGITAL_CLIENT_ID=your_client_id
IMPROVE_DIGITAL_CLIENT_SECRET=your_client_secret
IMPROVE_DIGITAL_API_BASE_URL=https://api.360yield.com
IMPROVE_DIGITAL_API_TIMEOUT_MS=60000

# Server Configuration
PORT=3000
TRANSPORT=http  # or 'stdio' for stdio transport
```

3. **Build and start:**
```bash
npm run build
npm start
```

### Development Mode
```bash
npm run dev  # Hot reload with tsx
```

## 🧪 Testing

Run the comprehensive test suite:
```bash
npm test
```

## 🧪 Using in MCP inspector

Run the MCP Inspector UI, then follow instructions:
```bash
npx @modelcontextprotocol/inspector
```

## 🧪 Using in Claude (as STDIO)

- Create the file `claude_desktop_config.json` with the following content:
```
{
  "mcpServers": {
    "improvedigital_mcp_server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/your/path/to/improvedigital-publisher-mcp-server/dist/src/index.js"
      ],
      "env": {
        "IMPROVE_DIGITAL_CLIENT_ID": "...",
        "IMPROVE_DIGITAL_CLIENT_SECRET": "...",
        "IMPROVE_DIGITAL_API_BASE_URL": "https://api.360yield.com",
        "IMPROVE_DIGITAL_API_TIMEOUT_MS": "60000",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

For mac the path is: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
For windows the path is: `C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json`

- Build the tool as described above.

- Launch Claude desktop (or restart if already running)

## 🧪 Using in Claude (as HTTP)

- Create the file `claude_desktop_config.json` with the following content:
```
{
  "mcpServers": {
    "improvedigital_mcp_server": {
      "command": "npx",
      "args": [ "mcp-remote", "http://<MCP_SERVER>:3000/mcp", "--allow-http" ]
    }
  }
}
```

For mac the path is: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
For windows the path is: `C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json`

- Run the mcp server in local machine and use value of `<MCP_SERVER>` as `localhost`.
  Or, use value of `<MCP_SERVER>` as any existing deployment host.

- Launch Claude desktop (or restart if already running)

## 🧪 Using in Cursor

- Add new MCP server (Settings => MCP Tools => New MCP Server) with the following content:
```
{
  "mcpServers": {
    "improvedigital_mcp_server": {
      "url": "http://<MCP_SERVER>:3000/mcp"
    }
  }
}
```

- Run the mcp server in local machine and use value of `<MCP_SERVER>` as `localhost`.
  Or, use value of `<MCP_SERVER>` as any existing deployment host.

- Enable the tool.

## Authentication
- OAuth2 Client Credentials provided via environment variables
- Bearer token management, token expiration handling

## 🛠️ Generated Tools
- `inventories_get_inventories`: GET /publisher/v1/publishers/{publisherId}/inventories
- `inventories_get_inventory_zones`: GET /publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones 
- `inventories_get_inventory_placements`: GET /publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements                                                                                                                        
- `inventories_get_inventory_placement`: GET /publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements/{placementId}
- `inventories_create_inventory_placement`: POST /publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements 
- `inventories_update_inventory_placement`: PUT /publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements/{placementId}

### Tool Schema Features
- **Path Parameters**: Automatically extracted and validated (e.g., `{publisherId}`)
- **Query Parameters**: Optional and required parameters with type validation
- **Request Bodies**: JSON schema generation from OpenAPI specifications
- **Schema References**: Full `$ref` resolution with circular reference protection

## 🔧 Configuration

### Transport Modes

**HTTP Transport** (Production):
```bash
TRANSPORT=http
PORT=3000
```
Access via: `http://localhost:3000/mcp`

**Stdio Transport** (Development):
```bash  
TRANSPORT=stdio
```

## Usage examples
Once the MCP server is successfully installed into your AI tool you can start managing inventory with your prompts.

### Example 1: List all inventories
```
List all inventories for publisher 1816
```

### Example 2: View zones in an inventory
```
Show me all zones under inventory 346036
```

### Example 3: List placements in a zone
```
List all placements in zone 17087058 under inventory 346036
```

### Example 4: Create a new placement
```
Create a new video preroll placement in zone 17087058 under inventory 346036.
Name it "Test Placement", set player size to 640x480, duration 1-30 seconds.
```

### Example 5: Copy an existing placement
```
Copy placement 22376222 and name it "My New Placement"
```

### Example 6: Update a placement
```
Update placement 22376237 to change the name to "Updated Placement Name"
```

## Programmatic use
It is also possible to use the module embedded into third party applications like custom agents. For this the
module exports the `createMcpContext` function that initializes the MCP tools and creates an MCP server instance.
Here is an example of possible usage:

```typescript
import { createMcpContext } from "@improvedigital/publisher-mcp-server";

// Initialize agent tools
const improveMcpContext = await createMcpContext({
  improveDigitalClientId: process.env.IMPROVE_DIGITAL_CLIENT_ID!,
  improveDigitalClientSecret: process.env.IMPROVE_DIGITAL_CLIENT_SECRET!,
});
const mcpClient = await initializeMcpConnection(improveMcpContext.mcpServer);
const improveTools = improveMcpContext.mcpTools.map(tool => convertMCPToolToLangChain(tool, mcpClient));

// Initialiaze agent
...
```

## License

This project is licensed under the MIT License - see below for details.

```
MIT License

Copyright (c) 2025 ImproveDigital

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## 🔗 Related Documentation

- [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol specification
- [OpenAPI Specification](https://swagger.io/specification/) - API documentation standard