AlenM666/MCP-server-assembly_x64_x86

MCP Server in x86_64 Assembly

A minimalist Model Context Protocol (MCP) server implementation written entirely in x86_64 assembly.

Features

• Pure x86_64 assembly implementation
• HTTP server with MCP protocol support
• Basic MCP capabilities including:
  • Server initialization
  • Tool listing
  • Tool execution (echo tool)
• CORS support for web clients
• Systemd service support
• No external dependencies beyond GNU binutils

Prerequisites

Make sure you have the required tools installed on Arch Linux:

# Install build tools
sudo pacman -S binutils

# Optional: Install curl for testing
sudo pacman -S curl

Building

# Check dependencies
make check-deps

# Build the server
make all

# Or build with debug symbols
make debug

Usage

Running the Server

# Run directly
make run

# Or run the binary
./mcp_server

The server will start on port 8080 and display:

MCP Server starting on port 8080...

Testing

Test the server with the built-in test suite:

make test

Or test manually with curl:

# Test server initialization
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# List available tools
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Call the echo tool
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"text":"Hello, World!"}}}'

Installation

System Installation

# Install to /usr/local/bin
make install

# Create and install systemd service
make service
sudo cp mcp-server.service /etc/systemd/system/
sudo systemctl enable mcp-server.service
sudo systemctl start mcp-server.service

Uninstallation

# Stop and disable service
sudo systemctl stop mcp-server.service
sudo systemctl disable mcp-server.service
sudo rm /etc/systemd/system/mcp-server.service

# Remove binary
make uninstall

Architecture

Protocol Support

The server implements a subset of the MCP 2024-11-05 specification:

• initialize: Server initialization and capability negotiation
• tools/list: Returns available tools (echo tool)
• tools/call: Executes the echo tool

Assembly Structure

• Socket Management: Creates and manages TCP sockets using Linux syscalls
• HTTP Handling: Parses basic HTTP requests and sends proper responses
• JSON Processing: Simple string matching for MCP JSON-RPC messages
• Error Handling: Returns proper MCP error responses for unknown methods

System Calls Used

• sys_socket (41): Create socket
• sys_bind (49): Bind to address
• sys_listen (50): Listen for connections
• sys_accept (43): Accept client connections
• sys_read (0): Read request data
• sys_write (1): Send responses
• sys_close (3): Close connections

Limitations

This is a minimal implementation with the following limitations:

• Single-threaded (handles one client at a time)
• Basic JSON parsing (string matching only)
• Limited error handling
• Fixed responses for tool calls
• No authentication or security features
• No logging to files

Development

Makefile Targets

• make all - Build the server
• make clean - Clean build artifacts
• make run - Build and run
• make debug - Build with debug symbols
• make test - Run automated tests
• make install - System installation
• make service - Create systemd service
• make help - Show all available targets

Debugging

Build with debug symbols and use GDB:

make debug
gdb ./mcp_server

Set breakpoints at key functions:

(gdb) break _start
(gdb) break server_loop
(gdb) break handle_mcp_request
(gdb) run

Contributing

This is a demonstration project showing low-level MCP implementation. To extend it:

1. Add proper JSON parsing for complex requests
2. Implement additional MCP methods
3. Add multi-threading support
4. Improve error handling and logging
5. Add more sophisticated tools

License

This code is provided as-is for educational and demonstration purposes. Use at your own risk in production environments.

Security Notice

This server runs with minimal security features. For production use, consider:

• Running as a non-privileged user
• Adding request validation
• Implementing rate limiting
• Using proper JSON parsing
• Adding authentication if needed