UTCP Documentation Server

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

TypeScript MCP License: 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

npm install -g utcp-docs

From Source

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:

{
  "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:

{
  "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:

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

// 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

// 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

// 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

# 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

# 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
• UTCP Specification
• UTCP vs MCP Comparison

MCP Resources

• Model Context Protocol
• MCP SDK Documentation
• MCP Servers Repository

🐛 Troubleshooting

Server Not Starting

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

Solution:

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:

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 file for details

🙏 Acknowledgments

• UTCP Team for creating the Universal Tool Calling Protocol
• Anthropic for the Model Context Protocol
• All contributors to this project

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

---

Built with ❤️ for the AI development community

Making UTCP implementation easier, one tool at a time.