# UTCP Documentation MCP Server

> A comprehensive MCP server that helps AI coding agents understand and implement the Universal Tool Calling Protocol (UTCP)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Features

- **🤖 LLM-Powered Expert Agent**: Ask questions in natural language to an OpenAI-powered agent with deep UTCP knowledge
- **📚 Documentation Search**: Semantic search across complete UTCP specification
- **✅ Manual Validation**: Validate UTCP manuals against v1.0.1 spec with detailed errors
- **🎨 Code Generation**: Generate UTCP manual templates for HTTP, CLI, MCP, SSE protocols
- **🔄 OpenAPI Conversion**: Convert OpenAPI 3.0 specs to UTCP manuals automatically
- **📝 Examples Library**: Ready-to-use examples for weather APIs, GitHub, databases, CLI tools
- **💡 Best Practices**: Built-in guidance for naming, authentication, and implementation

## 📦 Installation

### NPM

```bash
npm install -g utcp-docs
```

### From Source

```bash
git clone https://github.com/yourusername/utcp-docs-mcp-server.git
cd utcp-docs-mcp-server
npm install
npm run build
npm link
```

## 🔧 Configuration

### For Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "utcp-docs": {
      "command": "utcp-docs",
      "env": {
        "DOCS_PATH": "/path/to/utcp-docs",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

### For Cursor IDE

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "utcp-docs": {
      "command": "npx",
      "args": ["utcp-docs"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

### Environment Variables

Create a `.env` file or set in your MCP config:

```bash
# OpenAI API Key (required for ask_utcp_expert tool)
OPENAI_API_KEY=sk-...

# Documentation path (default: current directory)
DOCS_PATH=.

# Server configuration
SERVER_NAME=utcp-docs
SERVER_VERSION=1.0.0
LOG_LEVEL=info
```

## 🛠️ Available Tools

### 🆕 1. Ask UTCP Expert (LLM Agent)

**NEW!** Ask an OpenAI-powered agent any question about UTCP:

```typescript
{
  "tool": "ask_utcp_expert",
  "arguments": {
    "question": "How do I authenticate with bearer tokens?"
  }
}
```

**The agent:**
- Has deep knowledge of the entire UTCP specification
- Retrieves relevant documentation automatically
- Provides detailed explanations with code examples
- Includes source references
- Offers best practices and guidance

**Example Questions:**
- "What is body_template and when should I use it?"
- "Show me a complete HTTP tool example with OAuth2"
- "How do I chain CLI commands together?"
- "Why is my tool name failing validation?"

**Requires:** OpenAI API key (set `OPENAI_API_KEY` environment variable)

---

### 2. Search UTCP Documentation

Search the complete UTCP specification:

```typescript
{
  "tool": "search_utcp_docs",
  "arguments": {
    "query": "how to implement HTTP authentication",
    "section": "protocols",  // optional: introduction, protocols, guides, api
    "limit": 5               // optional: max results
  }
}
```

**Example Response:**
```
# Search Results for "HTTP authentication"

## Result 1: HTTP Protocol Authentication
**Section:** protocols
**Relevance:** 45

Authentication in HTTP protocols can be configured using the auth field...
```

### 3. Validate UTCP Manual

Validate your UTCP manual against the specification:

```typescript
{
  "tool": "validate_utcp_manual",
  "arguments": {
    "manual": {
      "manual_version": "1.0.0",
      "utcp_version": "1.0.1",
      "tools": [...]
    }
  }
}
```

**Response:**
```
✅ Valid UTCP Manual
The manual passes all validation checks and conforms to UTCP v1.0.1 specification.
```

Or with errors:
```
❌ Invalid UTCP Manual

## Errors
- /tools/0/name: Tool name "GetWeather" must use snake_case
- /tools/0/tool_call_template: HTTP template requires a URL

## Warnings
- /tools/0/description: Tool description should be at least 10 characters
```

### 4. Generate UTCP Manual

Generate a UTCP manual template:

```typescript
{
  "tool": "generate_utcp_manual",
  "arguments": {
    "tool_name": "get_weather",
    "description": "Get current weather for a location",
    "protocol": "http",
    "endpoint": "https://api.openweathermap.org/data/2.5/weather",
    "method": "GET",
    "parameters": {
      "location": {
        "type": "string",
        "description": "City name",
        "required": true
      }
    },
    "include_auth": true
  }
}
```

**Supported Protocols:**
- `http` - RESTful HTTP APIs
- `cli` - Command-line tools
- `mcp` - Model Context Protocol servers
- `sse` - Server-Sent Events
- `streamable_http` - Streaming HTTP responses

### 5. Convert OpenAPI to UTCP

Convert OpenAPI 3.0 specifications to UTCP manuals:

```typescript
{
  "tool": "convert_openapi_to_utcp",
  "arguments": {
    "openapi_spec": {
      "openapi": "3.0.0",
      "info": { "title": "My API", "version": "1.0.0" },
      "paths": {
        "/users": {
          "get": {
            "operationId": "getUsers",
            "summary": "List users"
          }
        }
      }
    }
  }
}
```

### 6. Get UTCP Examples

Get ready-to-use example UTCP manuals:

```typescript
{
  "tool": "get_utcp_examples",
  "arguments": {
    "use_case": "weather"  // weather, github, database, cli-tool
  }
}
```

**Available Examples:**
- `weather` - OpenWeatherMap API integration
- `github` - GitHub REST API (repos, issues)
- `database` - Database query tools via MCP
- `cli-tool` - Git command-line wrapper

### 7. Get Best Practices

Get UTCP implementation best practices:

```typescript
{
  "tool": "get_best_practices",
  "arguments": {
    "topic": "naming"  // naming, authentication, error-handling, testing, general
  }
}
```

## 📖 Resources

The server provides these resources via MCP:

| Resource URI | Description |
|--------------|-------------|
| `utcp://docs/full` | Complete UTCP documentation (9700+ lines) |
| `utcp://docs/introduction` | UTCP introduction and overview |
| `utcp://docs/protocols` | All protocol documentation |
| `utcp://examples/weather` | Weather API example manual |
| `utcp://examples/github` | GitHub API example manual |
| `utcp://schema/manual` | UTCP JSON Schema for validation |

## 🧪 Usage Examples

### Example 1: Creating a New UTCP Manual

```typescript
// 1. Generate a template
const result = await callTool("generate_utcp_manual", {
  tool_name: "send_email",
  description: "Send an email via SendGrid API",
  protocol: "http",
  endpoint: "https://api.sendgrid.com/v3/mail/send",
  method: "POST",
  parameters: {
    to: { type: "string", description: "Recipient email", required: true },
    subject: { type: "string", description: "Email subject", required: true },
    body: { type: "string", description: "Email body", required: true }
  },
  include_auth: true
});

// 2. Validate the generated manual
const validation = await callTool("validate_utcp_manual", {
  manual: JSON.parse(result)
});

// 3. Get best practices for authentication
const practices = await callTool("get_best_practices", {
  topic: "authentication"
});
```

### Example 2: Converting Existing OpenAPI Spec

```typescript
// 1. Read your OpenAPI spec
const openApiSpec = JSON.parse(fs.readFileSync("api-spec.json"));

// 2. Convert to UTCP
const utcpManual = await callTool("convert_openapi_to_utcp", {
  openapi_spec: openApiSpec
});

// 3. Validate the result
const validation = await callTool("validate_utcp_manual", {
  manual: JSON.parse(utcpManual)
});
```

### Example 3: Searching Documentation

```typescript
// Search for specific implementation details
const results = await callTool("search_utcp_docs", {
  query: "how to handle streaming responses",
  section: "protocols",
  limit: 3
});

// Get an example to reference
const example = await callTool("get_utcp_examples", {
  use_case: "github"
});
```

## 🏗️ Development

### Setup

```bash
# Clone repository
git clone https://github.com/yourusername/utcp-docs-mcp-server.git
cd utcp-docs-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev
```

### Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage
```

### Project Structure

```
utcp-docs/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── types/
│   │   └── utcp.ts           # TypeScript types
│   ├── services/
│   │   ├── documentation.ts  # Documentation search
│   │   ├── validator.ts      # UTCP validation
│   │   ├── generator.ts      # Manual generation
│   │   └── converter.ts      # OpenAPI conversion
│   └── schemas/
│       └── utcp-manual.schema.json
├── docs/
│   └── examples/             # Example UTCP manuals
├── tests/
│   └── services/             # Unit tests
├── llms.txt                  # Complete UTCP documentation
└── package.json
```

## 📋 Requirements

- **Node.js**: 20.x or higher
- **TypeScript**: 5.3 or higher
- **MCP SDK**: 1.0.4 or higher

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a 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

### Development Guidelines

- Write tests for new features
- Follow TypeScript best practices
- Update documentation for API changes
- Ensure all tests pass before submitting PR

## 📚 Resources

### UTCP Resources
- [UTCP Website](https://utcp.io/)
- [UTCP Specification](https://utcp.io/api-specification)
- [UTCP vs MCP Comparison](https://utcp.io/utcp-vs-mcp)

### MCP Resources
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)

## 🐛 Troubleshooting

### Server Not Starting

**Issue:** `Error: Cannot find module 'ajv-formats'`

**Solution:**
```bash
npm install ajv-formats
npm run build
```

### Documentation Not Loading

**Issue:** `Error loading llms.txt`

**Solution:** Ensure `DOCS_PATH` environment variable points to the correct directory:
```bash
export DOCS_PATH=/path/to/utcp-docs
```

### Validation Errors

**Issue:** Tool names failing validation

**Solution:** Use snake_case naming:
- ✅ `get_user_data`
- ❌ `GetUserData`
- ❌ `getUserData`

## 📄 License

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

## 🙏 Acknowledgments

- [UTCP Team](https://utcp.io/) for creating the Universal Tool Calling Protocol
- [Anthropic](https://www.anthropic.com/) for the Model Context Protocol
- All contributors to this project

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/utcp-docs/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/utcp-docs/discussions)
- **Email**: support@example.com

---

**Built with ❤️ for the AI development community**

*Making UTCP implementation easier, one tool at a time.*