AI Advent MCP Protocol Supplement

Version 1.0
Last Updated: 2025-01-22

1. Overview

1.1 What is MCP?

MCP (Model Control Protocol) is an extension to the AI Advent TCP protocol that lets clients register custom services so the server can actively invoke client-side functions.

1.2 Key Features

Service Registration: Clients can register any number of custom services

Bidirectional Invocation: Server can call client services proactively

Asynchronous Processing: Supports async invocation and responses

Standardized Interface: Service interfaces are defined with JSON Schema

1.3 Typical Use-Cases

Local file operations

System-information queries

Device-control interfaces

Custom business logic

2. MCP Message Types

2.1 Message-Type Constant

MCP uses message type \x06 for all its communications

2.2 Message Structure

MCP messages follow the standard TCP protocol format:

##START\x06[TaskID][Seq][JSON payload]##END

2.3 Task-ID Convention

Recommended fixed task-ID for MCP: mcp00001

Exactly 8 bytes; pad with spaces if shorter

Any other 8-byte identifier may be used when desired

3. Service Registration

3.1 When to Register

Clients may register MCP services immediately after authentication, or re-register at any time when local conditions change.

3.2 Registration Message Format

{
    "type": "register",
    "data": {
        "services": {
            "serviceName": {
                "description": "What this service does",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "paramName": {
                            "type":  "string|number|boolean|array|object",
                            "description": "Meaning of the parameter",
                            "enum": ["optional", "value", "list"]
                        }
                    },
                    "required": ["mandatoryParam1", "mandatoryParam2"]
                }
            }
        }
    }
}

3.3 Service-Definition Example

{
    "type": "register",
    "data": {
        "services": {
            "get_current_time": {
                "description": "Retrieve current date and time",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "format": {
                            "type": "string",
                            "enum": ["simple", "detailed"],
                            "description": "simple = short, detailed = full info"
                        }
                    }
                }
            },
            "create_file": {
                "description": "Create a local file and write content",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "filename": {
                            "type": "string",
                            "description": "Name of the file to create"
                        },
                        "content": {
                            "type": "string",
                            "description": "Text to write into the file"
                        }
                    },
                    "required": ["filename", "content"]
                }
            }
        }
    }
}

4. Service-Invocation Flow

4.1 Initiating a Call

When the server decides a client-side service is required, it sends a call message.

4.2 Call Message Format

{
    "type": "call",
    "data": {
        "call_id": "unique-call-identifier",
        "method": "serviceName",
        "params": {
            "paramName": "paramValue"
        }
    }
}

4.3 Response Message Format

After executing the service, the client must return the result:

{
    "type": "result",
    "data": {
        "call_id": "same-call-identifier",
        "result": {
            "success": true | false,
            "data": "return-value",
            "error": "error-message (only if success=false)"
        }
    }
}

4.4 Invocation Sequence

User sends request to server

Server parses request and decides a client service is required

Server sends MCP call message to client

Client receives call, executes the service

Client returns execution result

Server generates final response to user

5. Data-Format Specification

5.1 JSON-Schema Rules

Service definitions must comply with JSON Schema:

5.1.1 Primitive Types

string

number

integer

boolean

array

object

5.1.2 Parameter Constraints

required: list of mandatory parameters

enum: allowed values

minimum / maximum: numeric range

minLength / maxLength: string length limits

5.2 Return-Value Format

Every service must return a uniform result:

{
    "success": true,           // execution status
    "data": "payload",         // present when success=true
    "error": "error message"   // present when success=false
}

5.3 Encoding Rules

All JSON is UTF-8 encoded

Chinese characters are transmitted as-is—no extra escaping required

Ensure JSON is syntactically valid

6. Error Handling

6.1 Service-Registration Errors

Registering the same service name twice

Malformed JSON

Service definition violates JSON Schema

6.2 Service-Invocation Errors

Calling a non-existent service

Parameter type mismatch

Missing required parameters

Service throws an exception

6.3 Error-Response Format

{
    "type": "result",
    "data": {
        "call_id": "call-identifier",
        "result": {
            "success": false,
            "error": "detailed error message"
        }
    }
}

7. Example Implementation

7.1 Complete MCP Communication Example

# 1. Client registers service
C -&gt; S: ##START\x06mcp00001[0000]{
    "type": "register",
    "data": {
        "services": {
            "get_current_time": {
                "description": "Get current time",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "format": {
                            "type": "string",
                            "enum": ["simple", "detailed"]
                        }
                    }
                }
            }
        }
    }
}##END

# 2. User requests time
C -&gt; S: ##START\x04task12340000What time is it?##END
C -&gt; S: ##START\x03task12340001##END

# 3. Server invokes client service
S -&gt; C: ##START\x06mcp00001[0000]{
    "type": "call",
    "data": {
        "call_id": "call_001",
        "method": "get_current_time",
        "params": {
            "format": "simple"
        }
    }
}##END

# 4. Client returns result
C -&gt; S: ##START\x06mcp00001[0000]{
    "type": "result",
    "data": {
        "call_id": "call_001",
        "result": {
            "success": true,
            "data": "2025-01-22 14:30:25"
        }
    }
}##END

# 5. Server responds to user
S -&gt; C: ##START\x04task12340000It is 14:30:25 on 22 Jan 2025##END
S -&gt; C: ##START\x03task12340001##END

7.2 Python Implementation Example

7.2.1 Service Registration

7.2.2 Service-Call Handling

7.2.3 Returning Results

8. Best Practices

8.1 Service-Design Principles

Single Responsibility: one service = one concrete task

Parameter Validation: strictly check type and range of every input

Error Handling: return clear error messages and handle exceptions

Performance Aware: avoid long-blocking operations

8.2 Implementation Guidelines

Register Promptly: register services immediately after authentication

Unique IDs: keep call_id unique and correctly mapped

Exception-Safe: wrap every service call in try/except

Logging: log key invocation info for easier debugging

8.3 Testing Checklist

Functional: verify each service works as intended

Parameter: test all parameter combinations and edge cases

Error: confirm error paths behave correctly

Performance: ensure response times are acceptable

8.4 Security Considerations

Input Sanitisation: inspect and cleanse incoming parameters

Access Control: restrict who can trigger sensitive operations

Data Validation: verify legality and integrity of all data

Resource Limits: prevent abuse and memory leaks

Notes:

MCP requires server-side support—confirm server version first

Test MCP services thoroughly in a staging environment

Pay attention to security and performance impact in production

Connect with MCP

AI Advent MCP Protocol Supplement#

Table of Contents#

1. Overview#

1.1 What is MCP?#

1.2 Key Features#

1.3 Typical Use-Cases#

2. MCP Message Types#

2.1 Message-Type Constant#

2.2 Message Structure#

2.3 Task-ID Convention#

3. Service Registration#

3.1 When to Register#

3.2 Registration Message Format#

3.3 Service-Definition Example#

4. Service-Invocation Flow#

4.1 Initiating a Call#

4.2 Call Message Format#

4.3 Response Message Format#

4.4 Invocation Sequence#

5. Data-Format Specification#

5.1 JSON-Schema Rules#

5.1.1 Primitive Types#

5.1.2 Parameter Constraints#

5.2 Return-Value Format#

5.3 Encoding Rules#

6. Error Handling#

6.1 Service-Registration Errors#

6.2 Service-Invocation Errors#

6.3 Error-Response Format#

7. Example Implementation#

7.1 Complete MCP Communication Example#

7.2 Python Implementation Example#

7.2.1 Service Registration#

7.2.2 Service-Call Handling#

7.2.3 Returning Results#

8. Best Practices#

8.1 Service-Design Principles#

8.2 Implementation Guidelines#

8.3 Testing Checklist#

8.4 Security Considerations#