Missing API reference resource for proxmox_api_call tool #1

New Issue

b3nw · 2026-01-05T11:01:20-06:00

b3nw commented

2026-01-05 11:01:20 -06:00

Summary

The proxmox-mcp-custom server does not follow the Hybrid MCP Light pattern defined in BLUEPRINT.md. It has the API pass-through tool (proxmox_api_call) but is missing the required documentation resource.

What's Missing

A @mcp.resource() decorator exposing API documentation at proxmox://api-reference.

Expected Pattern

Per BLUEPRINT.md section 4 ("The Documentation Resource"), the server should expose the Proxmox VE API documentation so agents can discover available endpoints:

API_DOCS = """
# Proxmox VE API Reference

## Nodes
GET /nodes - List all nodes
GET /nodes/{node}/status - Get node status
...

## Virtual Machines
GET /nodes/{node}/qemu - List VMs on node
GET /nodes/{node}/qemu/{vmid}/status/current - Get VM status
POST /nodes/{node}/qemu/{vmid}/status/start - Start VM
POST /nodes/{node}/qemu/{vmid}/status/stop - Stop VM
...

## Containers
GET /nodes/{node}/lxc - List containers on node
...
"""

@mcp.resource("proxmox://api-reference")
def get_api_docs() -> str:
    """Returns the Proxmox VE API documentation for using the 'proxmox_api_call' tool."""
    return API_DOCS

Compliant Examples

All other MCP servers in the project have this resource:

komodo-mcp-custom - komodo://api-reference
plex-mcp-custom - plex://api-reference
gitea-mcp-custom - gitea://api-reference
n8n-mcp-custom - n8n://api-reference

Impact

Without this resource, AI agents cannot programmatically discover how to use the proxmox_api_call tool effectively. They must rely solely on the tool's docstring or external knowledge of the Proxmox API.

Reference

Proxmox VE API Documentation
BLUEPRINT.md in the mcp project root

## Summary The `proxmox-mcp-custom` server does not follow the Hybrid MCP Light pattern defined in `BLUEPRINT.md`. It has the API pass-through tool (`proxmox_api_call`) but is missing the required documentation resource. ## What's Missing A `@mcp.resource()` decorator exposing API documentation at `proxmox://api-reference`. ## Expected Pattern Per BLUEPRINT.md section 4 ("The Documentation Resource"), the server should expose the Proxmox VE API documentation so agents can discover available endpoints: ```python API_DOCS = """ # Proxmox VE API Reference ## Nodes GET /nodes - List all nodes GET /nodes/{node}/status - Get node status ... ## Virtual Machines GET /nodes/{node}/qemu - List VMs on node GET /nodes/{node}/qemu/{vmid}/status/current - Get VM status POST /nodes/{node}/qemu/{vmid}/status/start - Start VM POST /nodes/{node}/qemu/{vmid}/status/stop - Stop VM ... ## Containers GET /nodes/{node}/lxc - List containers on node ... """ @mcp.resource("proxmox://api-reference") def get_api_docs() -> str: """Returns the Proxmox VE API documentation for using the 'proxmox_api_call' tool.""" return API_DOCS ``` ## Compliant Examples All other MCP servers in the project have this resource: - `komodo-mcp-custom` - `komodo://api-reference` - `plex-mcp-custom` - `plex://api-reference` - `gitea-mcp-custom` - `gitea://api-reference` - `n8n-mcp-custom` - `n8n://api-reference` ## Impact Without this resource, AI agents cannot programmatically discover how to use the `proxmox_api_call` tool effectively. They must rely solely on the tool's docstring or external knowledge of the Proxmox API. ## Reference - [Proxmox VE API Documentation](https://pve.proxmox.com/pve-docs/api-viewer/index.html) - BLUEPRINT.md in the mcp project root

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: b3nw/proxmox-mcp-custom#1