744 annotations

[crivetimihai]

Closes #774

Root Cause

The issue was in the admin_add_tool and admin_edit_tool functions in mcpgateway/admin.py. The form parsing code was missing the annotations field extraction:

# Before (missing annotations)
tool_data: dict[str, Any] = {
    "name": form.get("name"),
    "url": form.get("url"),
    "description": form.get("description"),
    "headers": json.loads(form.get("headers") or "{}"),
    "input_schema": json.loads(form.get("input_schema") or "{}"),
    # annotations missing here!
    "jsonpath_filter": form.get("jsonpathFilter", ""),
    # ... rest of fields
}

Fix Applied

Files Changed: mcpgateway/admin.py

Added the missing annotations field parsing in both functions:

# After (annotations now included)
tool_data: dict[str, Any] = {
    "name": form.get("name"),
    "url": form.get("url"),
    "description": form.get("description"),
    "headers": json.loads(form.get("headers") or "{}"),
    "input_schema": json.loads(form.get("input_schema") or "{}"),
    "annotations": json.loads(form.get("annotations") or "{}"),  # ✅ Fixed
    "jsonpath_filter": form.get("jsonpathFilter", ""),
    # ... rest of fields
}

Lines changed:

• Line 1971: admin_add_tool function
• Line 2203: admin_edit_tool function

What This Fixes

✅ Admin UI Creation: Users can now set annotations when creating tools via the web interface
✅ Admin UI Editing: Users can now modify annotations when editing tools via the web interface
✅ Persistence: Annotations will now be properly saved to the database
✅ Display: Annotations will appear correctly in tool JSON responses
✅ API Compatibility: Existing API functionality remains unchanged

API Documentation (as requested)

Complete Annotations JSON Example

Here's a comprehensive example with all supported annotation types:

curl -X POST /tools \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "file-reader",
    "url": "http://example.com/api/read-file",
    "description": "Safely reads file contents",
    "annotations": {
      "readOnlyHint": true,
      "destructiveHint": false,
      "idempotentHint": true,
      "openWorldHint": false
    }
  }'

Individual Annotation Examples

Read-Only Tool:

{
  "name": "get-user-info",
  "url": "http://api.example.com/users",
  "annotations": {
    "readOnlyHint": true
  }
}

Destructive Tool:

{
  "name": "delete-file",
  "url": "http://api.example.com/files/delete",
  "annotations": {
    "destructiveHint": true,
    "idempotentHint": false
  }
}

Idempotent Tool:

{
  "name": "create-user",
  "url": "http://api.example.com/users",
  "annotations": {
    "idempotentHint": true,
    "readOnlyHint": false
  }
}

Updating tool annotations:

curl -X PUT /tools/{tool_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "annotations": {
      "readOnlyHint": true,
      "destructiveHint": false
    }
  }'

For gateway-discovered tools:

1. Register the gateway first (tools auto-discovered):

   curl -X POST /gateways \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "name": "my-mcp-server",
       "url": "http://localhost:8080/sse"
     }'

2. Add annotations to discovered tools via PUT /tools/{tool_id}:

   curl -X PUT /tools/{discovered_tool_id} \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "annotations": {
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true
       }
     }'

Testing Status

✅ Syntax validation: Code compiles successfully
✅ Linting: All lint checks pass (10.00/10 maintained)
✅ Consistency: Both add and edit functions now handle annotations identically

Expected Behavior

After this fix, users should be able to:

1. Set annotations in Admin UI using JSON format like:

   {
     "readOnlyHint": true,
     "destructiveHint": false
   }

2. See annotations persist in database and API responses

3. Use all supported annotation types as documented in the MCP specification

The backend infrastructure was already complete - this was purely a UI form parsing issue. The fix is minimal, safe, and maintains full backward compatibility.

📚 Enhanced Documentation

I've also added comprehensive documentation for tool annotations:

New Documentation: docs/docs/using/tool-annotations.md

This includes:

• ✅ Complete annotation reference with all supported types
• ✅ Real-world examples for different tool scenarios
• ✅ Best practices for annotation usage
• ✅ Integration guidance for clients and UIs
• ✅ Step-by-step workflows for gateway-discovered tools

The documentation is also now linked from the main using guide for easy discovery.

[KaRtHiK-56]

Thanks for the quick response and quick fix @crivetimihai