# Kiota MCP Server

MCP server that exposes all Kiota CLI commands as MCP tools for API client generation.

## Overview

The Kiota MCP Server provides a Model Context Protocol interface to the Kiota CLI, enabling AI assistants and MCP clients to:

- 🔍 **Search** for API descriptions
- ⬇️ **Download** OpenAPI specifications
- ⚙️ **Manage** client configurations (add, edit, remove)
- 🚀 **Generate** type-safe API client code with automatic dependency detection
- ℹ️ **Query** language support and dependency information

## Prerequisites

Before using the Kiota MCP Server, ensure you have:

- **Node.js v20 LTS or higher**
- **MCP-compatible client** (e.g., Claude Desktop, MCP Inspector)

**Note**: Kiota CLI is bundled as a dependency and will be installed automatically. No separate installation required.

## Installation

```bash
npm install kiota-mcp
```

## Usage

### As MCP Server

Configure in your MCP client settings (e.g., Claude Desktop):

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

### Available Tools

The server exposes 7 MCP tools corresponding to Kiota CLI commands:

1. **`kiota_search`** - Search for API descriptions
2. **`kiota_download`** - Download OpenAPI specifications
3. **`kiota_client_add`** - Add new client configuration
4. **`kiota_client_edit`** - Update existing client configuration
5. **`kiota_client_generate`** - Generate API client code (with automatic `--ebc` flag)
6. **`kiota_client_remove`** - Remove client configuration
7. **`kiota_info`** - Query language support and dependencies

## Quick Start

### 1. Search for an API

```json
{
  "tool": "kiota_search",
  "params": {
    "searchTerm": "GitHub"
  }
}
```

### 2. Download OpenAPI Specification

```json
{
  "tool": "kiota_download",
  "params": {
    "openApiUrl": "https://api.github.com/openapi.json",
    "outputPath": "./github-api-spec.json"
  }
}
```

### 3. Add Client Configuration

```json
{
  "tool": "kiota_client_add",
  "params": {
    "clientName": "github-api",
    "openApiPath": "./github-api-spec.json",
    "language": "typescript",
    "outputPath": "./generated/github"
  }
}
```

### 4. Generate Client Code

```json
{
  "tool": "kiota_client_generate",
  "params": {
    "clientName": "github-api"
  }
}
```

The tool automatically:

- Uses `--ebc` flag for error-based cancellation
- Runs `kiota info` to determine required dependencies
- Returns installation commands for dependencies

## OpenAPI Requirements

The Kiota MCP Server works with:

- ✅ **OpenAPI 3.0.x and 3.1.x** specifications
- ✅ **JSON and YAML** formats
- ✅ **Local file paths** or **HTTPS URLs**
- ⚠️ Maximum file size: **10MB**

## Supported Languages

- TypeScript
- JavaScript
- C#
- Java
- Python
- Go
- PHP
- Ruby
- Swift

Query available languages with:

```json
{
  "tool": "kiota_info",
  "params": {}
}
```

## Environment

The server automatically sets `KIOTA_CONFIG_PREVIEW=true` for all Kiota CLI operations, enabling preview features.

## Development

### Build

```bash
npm run build
```

### Test

```bash
# Run all tests
npm test

# Watch mode (TDD)
npm run test:watch

# Coverage report
npm run test:coverage
```

### Lint

```bash
npm run lint
npm run lint:fix
```

## Documentation

- [User Guide](./docs/guides/getting-started.md)
- [API Reference](./docs/api/)
- [Examples](./docs/examples/)
- [Troubleshooting](./docs/guides/troubleshooting.md)

## Architecture

- **TypeScript 5.7+** with strict mode
- **Vitest** for testing (TDD workflow)
- **MCP SDK** for protocol implementation
- **Kiota CLI** delegation (no reimplementation)

## License

MIT

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.

## Constitution

This project follows strict development principles documented in [`.specify/memory/constitution.md`](.specify/memory/constitution.md):

- 🎯 OpenAPI-First Architecture
- 📘 TypeScript & Modern Tooling
- 🧪 Test-Driven Development (TDD) - NON-NEGOTIABLE
- 📚 Documentation Excellence
- 👤 User-Provided Specifications
- 💻 Local MVP Server