npm package: @iwy/mcp
Description: Model Context Protocol (MCP) server for iwy.ai API integration - enables Claude to manage AI agents and tools
Author: iwy.ai
Latest version: 0.4.0

# iwy.ai MCP Server

[![npm version](https://badge.fury.io/js/%40iwy%2Fmcp.svg)](https://www.npmjs.com/package/@iwy/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> ⚠️ **Beta Pre-Release* - This is an early version. API may change.

Model Context Protocol (MCP) server for [iwy.ai](https://iwy.ai) - enables Claude to create and manage AI agents and tool integrations through the iwy.ai API.

## Features

- **Complete Agent Management**: Create, read, update, and delete AI conversational agents
- **Tool Integration**: Manage webhook-based tools for agent capabilities
- **Testing Support**: Test tools before deploying to production agents
- **Comprehensive Documentation**: Built-in API reference and configuration guides
- **Type Safety**: Full TypeScript support with Zod validation
- **Robust Error Handling**: Automatic retries and detailed error messages

## Installation

### Global Installation (Recommended)

```bash
npm install -g @iwy/mcp
```

### Local Installation

```bash
npm install @iwy/mcp
```

## Configuration

### 1. Get Your API Key

1. Visit [app.iwy.ai/settings](https://app.iwy.ai/settings)
2. Generate a new API key
3. Save it securely

### 2. Configure Claude

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "iwy": {
      "command": "npx",
      "args": ["-y", "@iwy/mcp"],
      "env": {
        "IWY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

#### Claude Code

**Installation Steps:**

1. Install the package globally:
```bash
npm install -g @iwy/mcp
```

2. Use `jq` to add the server to `~/.claude.json`:
```bash
jq '.mcpServers["iwy"] = {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@iwy/mcp"],
  "env": {
    "IWY_API_KEY": "your_api_key_here"
  }
}' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json
```

Or manually edit `~/.claude.json` and add to the `mcpServers` object:

```json
{
  "mcpServers": {
    "iwy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@iwy/mcp"],
      "env": {
        "IWY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

3. Restart Claude Code to load the MCP server.

**Testing:**
```
# List your agents
"List my iwy.ai agents"

# Get agent details
"Show me details for agent <agent_id>"

# Create a new agent
"Create an iwy.ai customer service agent"
```

### 3. Environment Variable

Alternatively, set the API key as an environment variable:

```bash
export IWY_API_KEY="your_api_key_here"
```

## Known Issues

### API Endpoint Version (Current Package)

The current npm package version may use the wrong API endpoint (`https://api.iwy.ai` instead of `https://api.iwy.ai/v1`). This has been identified and will be fixed in the next release.

**Temporary Workaround (if you encounter "Resource not found" errors):**

Find your global npm packages location and update the API client:

```bash
# Find the installation path
NPM_PATH=$(npm root -g)/@iwy/mcp/dist/client.js

# Update the baseURL
sed -i "s|baseURL: 'https://api.iwy.ai'|baseURL: 'https://api.iwy.ai/v1'|" "$NPM_PATH"
```

This will be resolved in version 0.2.2+.

## Available Tools

### Agent Management (5 tools)

| Tool | Description |
|------|-------------|
| `list_iwy_agents` | List all agents in your account |
| `get_iwy_agent` | Get detailed agent configuration |
| `create_iwy_agent` | Create a new AI agent |
| `update_iwy_agent` | Update existing agent |
| `delete_iwy_agent` | Delete an agent |

### Tool Management (6 tools)

| Tool | Description |
|------|-------------|
| `list_iwy_tools` | List all webhook tools |
| `get_iwy_tool` | Get detailed tool configuration |
| `create_iwy_tool` | Create a new tool integration |
| `update_iwy_tool` | Update existing tool |
| `delete_iwy_tool` | Delete a tool |
| `test_iwy_tool` | Test tool execution |

## Usage Examples

### Creating a Customer Service Agent

```
User: Create a customer service agent for my e-commerce store

Claude: I'll create an iwy.ai agent for customer service.

[Creates agent with appropriate configuration]

✅ Created agent with ID: 550e8400-e29b-41d4-a716-446655440000
```

### Adding a Weather Tool

```
User: Add a weather lookup tool

Claude: I'll create a tool integration for weather lookup.

[Creates tool with webhook configuration]

✅ Created tool with ID: dcfae097-1b37-4444-bb0c-1a6abb0320fd
```

### Testing a Tool

```
User: Test the weather tool with "San Francisco"

Claude: [Tests tool with parameters]

✅ Test successful!
- Execution time: 245ms
- Response: {"temperature": 68, "conditions": "sunny"}
```

## Documentation Resources

The server provides three built-in documentation resources accessible through Claude:

- `iwy://docs/agents` - Agent API reference
- `iwy://docs/tools` - Tool API reference
- `iwy://docs/configuration` - Setup and configuration guide

## Development

### Building from Source

```bash
git clone https://github.com/iwy-ai/mcp.git
cd mcp
npm install
npm run build
```

### Running Locally

```bash
export IWY_API_KEY="your_api_key_here"
node dist/index.js
```

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── client.ts             # iwy.ai API client
├── types.ts              # TypeScript type definitions
├── schemas/
│   ├── agent.ts          # Agent validation schemas
│   └── tool.ts           # Tool validation schemas
├── tools/
│   ├── agents.ts         # Agent tool handlers
│   └── tools.ts          # Tool tool handlers
├── utils/
│   ├── errors.ts         # Error handling
│   └── validation.ts     # Input validation
└── resources/
    ├── agent-docs.md     # Agent documentation
    ├── tool-docs.md      # Tool documentation
    └── config-guide.md   # Configuration guide
```

## Error Handling

The server provides detailed error messages with suggestions:

| Error Code | Description | Suggestion |
|------------|-------------|------------|
| `UNAUTHORIZED` | Invalid API key | Check IWY_API_KEY configuration |
| `NOT_FOUND` | Resource doesn't exist | Use list operation to find valid IDs |
| `INVALID_REQUEST` | Validation failed | Check required fields and types |
| `SERVER_ERROR` | iwy.ai API error | Automatic retry, contact support if persists |
| `TIMEOUT` | Request timeout | Increase timeout or retry |

## Requirements

- Node.js >= 18.0.0
- iwy.ai API key from [app.iwy.ai/settings](https://app.iwy.ai/settings)

## License

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

## Links

- [iwy.ai Website](https://iwy.ai)
- [iwy.ai Documentation](https://docs.iwy.ai)
- [API Reference](https://docs.iwy.ai/api-reference)
- [Changelog](CHANGELOG.md)
- [MCP Specification](https://spec.modelcontextprotocol.io)
- [GitHub Repository](https://github.com/iwy-ai/mcp)
- [Report Issues](https://github.com/iwy-ai/mcp/issues)

## Support

For issues, questions, or feature requests:

- Open a [GitHub issue](https://github.com/iwy-ai/mcp/issues)
- Check the [documentation](https://docs.iwy.ai)
- Contact iwy.ai support

## 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/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request