Skip to content

MCP_TOOL_SPECIFICATION.md

Latest commit

 

History

History
292 lines (207 loc) · 9.1 KB

MCP_TOOL_SPECIFICATION.md

File metadata and controls

292 lines (207 loc) · 9.1 KB

Edge Computing - MCP Tool Specification

This document defines the Model Context Protocol tools for the Edge Computing module, covering function deployment, node health monitoring, state synchronization, and cluster inventory.

General Considerations

  • Latency Sensitivity: Edge operations are designed for low-latency environments. Tool responses should be fast.
  • State Sync: Synchronization uses version-based conflict resolution (highest version wins).
  • Node Lifecycle: Nodes must be registered before functions can be deployed to them.

Tool: edge_deploy_function

1. Tool Purpose and Description

Deploys a function to one or more edge nodes. Can target a specific node or broadcast to all nodes in the cluster.

2. Invocation Name

edge_deploy_function

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
function_id string Yes Unique function identifier "fn-process-img"
function_name string Yes Human-readable function name "process-image"
node_id string No Target node (omit to deploy to all) "edge-01"
memory_mb integer No Memory allocation in MB (default: 128) 256
timeout_seconds integer No Execution timeout (default: 30) 60
environment object No Environment variables for the function {"MODEL": "yolo-v8"}

4. Output Schema (Return Value)

Field Name Type Description Example Value
status string "deployed" or "error" "deployed"
function_id string Deployed function ID "fn-process-img"
deployed_to array[string] Node IDs where function was deployed ["edge-01", "edge-02"]
deploy_count integer Number of nodes 2

5. Error Handling

  • Node Not Found: Returns error if node_id is specified but not registered.
  • No Nodes Available: Returns error if cluster has no registered nodes.
  • Duplicate Deploy: Overwrites existing function with same ID on the node (not an error).

6. Idempotency

  • Idempotent: Yes. Redeploying the same function overwrites the previous deployment.

7. Usage Examples

{
  "tool_name": "edge_deploy_function",
  "arguments": {
    "function_id": "fn-process-img",
    "function_name": "process-image",
    "node_id": "edge-01",
    "memory_mb": 256,
    "timeout_seconds": 60
  }
}
{
  "tool_name": "edge_deploy_function",
  "arguments": {
    "function_id": "fn-health-check",
    "function_name": "health-check"
  }
}

8. Security Considerations

  • Function Code: The MCP tool deploys function metadata; actual handler code must be pre-registered in the runtime.
  • Environment Variables: May contain secrets; ensure transport encryption.
  • Authorization: Restrict deployment to authorized operators.

Tool: edge_node_status

1. Tool Purpose and Description

Retrieves health and status information for one or all edge nodes, including last heartbeat, capabilities, and deployed functions.

2. Invocation Name

edge_node_status

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
node_id string No Specific node (default: all nodes) "edge-01"
include_functions boolean No Include deployed function list (default: false) true

4. Output Schema (Return Value)

Field Name Type Description Example Value
nodes array[object] Node status list See below
total_nodes integer Total registered nodes 5
online_count integer Nodes with ONLINE status 4

Each node object:

Field Name Type Description Example Value
id string Node ID "edge-01"
name string Node name "warehouse-sensor"
status string Current status "online"
location string Physical location "Building A, Rack 3"
last_heartbeat string ISO timestamp "2026-02-05T10:00:00Z"
capabilities array[string] Node capabilities ["gpu", "camera"]
functions array[object] Deployed functions (if requested) [{"id": "fn-1", "name": "..."}]

5. Error Handling

  • Node Not Found: Returns empty nodes array if node_id does not match.

6. Idempotency

  • Idempotent: Yes. Read-only query.

7. Usage Examples

{
  "tool_name": "edge_node_status",
  "arguments": {
    "node_id": "edge-01",
    "include_functions": true
  }
}

8. Security Considerations

  • Read-only. Node locations, capabilities, and function lists may reveal infrastructure topology.

Tool: edge_sync

1. Tool Purpose and Description

Triggers or queries state synchronization between edge nodes and the central cloud. Can push local changes, pull remote state, or report sync status.

2. Invocation Name

edge_sync

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
action string Yes "push", "pull", "status", or "confirm" "push"
node_id string No Target node for sync "edge-01"
data object No Data to sync (required for push) {"key": "value"}
version integer No Version number (required for confirm) 5

4. Output Schema (Return Value)

Field Name Type Description Example Value
status string "synced", "pending", "confirmed", or "error" "synced"
version integer Current state version 5
checksum string MD5 checksum of current state "a1b2c3d4..."
pending_changes integer Number of unsynced changes 0
last_sync string ISO timestamp of last sync "2026-02-05T10:00:00Z"

5. Error Handling

  • No Local State: pull or status with no existing state returns version 0.
  • Missing Data: push without data returns error.
  • Version Conflict: pull with a version older than local is a no-op (returns current state).

6. Idempotency

  • push: Not idempotent (increments version).
  • pull: Idempotent (applies only if remote is newer).
  • status: Idempotent (read-only).
  • confirm: Idempotent (confirming already-confirmed changes is a no-op).

7. Usage Examples

{
  "tool_name": "edge_sync",
  "arguments": {
    "action": "push",
    "node_id": "edge-01",
    "data": {"sensor_readings": [22.5, 23.1, 21.8]}
  }
}
{
  "tool_name": "edge_sync",
  "arguments": {
    "action": "status",
    "node_id": "edge-01"
  }
}

8. Security Considerations

  • Data Integrity: Checksums verify state consistency. Validate checksums on both ends.
  • Transport Security: Sync data may contain sensitive operational state; encrypt in transit.
  • Version Ordering: Version-based resolution prevents stale writes but does not merge conflicts.

Tool: edge_list_nodes

1. Tool Purpose and Description

Lists all registered edge nodes in the cluster, optionally filtered by status. A lightweight alternative to edge_node_status for inventory queries.

2. Invocation Name

edge_list_nodes

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
status_filter string No Filter by status: "online", "offline", "degraded", "syncing" "online"

4. Output Schema (Return Value)

Field Name Type Description Example Value
nodes array[object] Minimal node list See below
total integer Total matching nodes 3

Each node object:

Field Name Type Description Example Value
id string Node ID "edge-01"
name string Node name "warehouse-sensor"
status string Current status "online"
location string Physical location "Building A"

5. Error Handling

  • Invalid Status: Returns error if status_filter is not a valid EdgeNodeStatus value.
  • Returns empty nodes array if no nodes match the filter.

6. Idempotency

  • Idempotent: Yes. Read-only query.

7. Usage Examples

{
  "tool_name": "edge_list_nodes",
  "arguments": {
    "status_filter": "online"
  }
}
{
  "tool_name": "edge_list_nodes",
  "arguments": {}
}

8. Security Considerations

  • Read-only. Minimal data exposure compared to edge_node_status.
  • Node IDs and locations may still reveal infrastructure details.

Navigation Links