🌐 LinkSphere MCP

Connect AI to the Physical World

A powerful Model Context Protocol (MCP) server that enables AI assistants to discover, connect to, and control nearby devices through a simple, intuitive interface.

✨ Features

• 🔍 Device Discovery - Scan for nearby Bluetooth, WiFi, USB, and Network devices
• 📡 Smart Connection - Connect and disconnect from devices seamlessly
• 🎮 Device Control - Control connected devices with simple commands
• 🚀 Streamable HTTP - Fast, stateless HTTP transport for maximum compatibility
• 🔒 Secure - Built-in session management and error handling
• 📦 Zero Configuration - Works out of the box with sensible defaults

🎯 Use Cases

• Smart Home Control - Manage IoT devices, smart lights, thermostats
• Audio Management - Control Bluetooth speakers, headphones, volume
• Network Management - Monitor and connect to WiFi networks
• Device Monitoring - Track nearby devices and their status
• Automation - Build AI-powered device automation workflows

🚀 Quick Start

Installation

npm install linksphere-mcp

Running the Server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm run start:http

The server will start on http://localhost:3000 by default.

Configuration

Create a .env file in the root directory:

PORT=3000
NODE_ENV=production

🔧 MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop's mcp.json):

{
  "mcpServers": {
    "linksphere": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}

📚 Available Tools

1️⃣ show - Discover Nearby Devices

Scan for nearby devices based on type.

Parameters:

• deviceType (required): Type of devices to discover
  • bluetooth - Bluetooth devices (headphones, speakers, etc.)
  • wifi - WiFi networks
  • usb - USB connected devices
  • network - Network/IoT devices

Example:

show nearby bluetooth devices

Response:

Found 4 device(s):

### 📱 Device 1: AirPods Pro
- Type: Audio Device
- Signal: -45 dBm (Excellent)
- MAC: A4:5E:60:E8:2C:1F
- Status: Connected
- Details: High-quality wireless earbuds...

2️⃣ connect - Connect to Devices

Establish or terminate connections with devices.

Parameters:

• deviceName (required): Name or identifier of the device
• action (required): connect or disconnect

Example:

connect to AirPods Pro

Response:

✅ Connection Successful

Device: AirPods Pro
Type: BLUETOOTH
MAC: A4:5E:60:E8:2C:1F
Status: Connected

3️⃣ control - Control Connected Devices

Send commands to connected devices.

Parameters:

• deviceName (required): Name of the connected device
• operation (required): Operation to perform
  • turn_on / turn_off - Power control
  • set_volume - Adjust volume (0-100)
  • set_brightness - Adjust brightness (0-100)
  • play / pause - Media control
  • noise_cancellation - Enable ANC
  • bass_boost - Audio enhancement
  • print / scan - Printer operations
• value (optional): Value for the operation

Example:

set AirPods Pro volume to 75

Response:

🎮 Device Control Executed

Device: AirPods Pro
Operation: SET VOLUME
Value: 75
Result: Volume set to 75%

🔄 Complete Workflow

graph LR
    A[🔍 Show Devices] --> B[📡 Connect]
    B --> C[🎮 Control]
    C --> D[🔌 Disconnect]

1. Discover devices using show
2. Connect to a device using connect
3. Control the device using control
4. Disconnect when done

🏗️ Architecture

LinkSphere-MCP/
├── src/
│   ├── index.ts          # MCP server entry point
│   └── tools/            # Tool implementations
│       ├── show.ts       # Device discovery
│       ├── connect.ts    # Connection management
│       └── control.ts    # Device control
├── package.json
├── tsconfig.json
└── README.md

🛠️ Development

# Clone the repository
git clone https://github.com/guangxiangdebizi/LinkSphere-MCP.git

# Install dependencies
npm install

# Build the project
npm run build

# Start development server
npm run dev

📡 API Endpoints

• GET /health - Health check endpoint
• POST /mcp - Main MCP JSON-RPC endpoint

🔒 Security

• Session-based authentication
• Request validation
• Error handling and sanitization
• CORS support for cross-origin requests

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

Apache License 2.0 - see the LICENSE file for details.

👤 Author

Xingyu Chen

• 🌐 LinkedIn: Xingyu Chen
• 📧 Email: [email protected]
• 💻 GitHub: @guangxiangdebizi
• 📦 npm: @xingyuchen

🙏 Acknowledgments

Built with:

• Model Context Protocol SDK
• Express.js
• TypeScript