Content
# Android MCP Server
An Android server application based on the MCP Kotlin SDK, using the SSE (Server-Sent Events) transport protocol.
## Features
- 🚀 **Complete MCP Server** - Complete Model Context Protocol server implementation
- 📡 **SSE Transport Protocol** - Real-time communication using Server-Sent Events
- 🎨 **Material Design** - Modern Android UI design
- 🔧 **Rich Toolset** - Device information, time query, and other example tools
- 📚 **Resource Management** - Access to system information and other resources
- 💡 **Intelligent Tips** - Device analysis and other tips
- 📱 **Background Service** - Foreground service ensures server continuous operation
- 📊 **Real-time Logs** - View server operation status and logs
## Technical Stack
- **Kotlin 2.1.0** - Modern programming language
- **MCP Kotlin SDK 0.5.0** - Official MCP SDK
- **Ktor** - High-performance HTTP server
- **Android Jetpack** - Modern Android development components
- **Material Design 3** - Latest design system
## Quick Start
### Requirements
- Android Studio Hedgehog | 2023.1.1 or higher
- Android SDK API 24 (Android 7.0) or higher
- Kotlin 2.1.0
- Gradle 8.4
### Installation Steps
1. **Clone the Project**
```bash
git clone <repository-url>
cd mcp-kotlin
```
2. **Open in Android Studio**
- Open Android Studio
- Choose "Open an existing project"
- Select the project directory
3. **Sync Gradle**
- Android Studio will automatically prompt to sync
- Wait for dependency download to complete
4. **Run the Application**
- Connect an Android device or start an emulator
- Click the "Run" button
### Quick Test
1. **Build the Project**
- Build → Clean Project
- Build → Rebuild Project
2. **Run the Application**
- Run the application
- Start the server
- Test MCP connection
### Usage
1. **Start the Server**
- Open the application
- Configure the port number (default 8080)
- Set the server name
- Click "Start Server"
2. **Connection Test**
- Homepage: `http://localhost:8080/`
- SSE Endpoint: `http://localhost:8080/sse`
- Status Query: `http://localhost:8080/status`
- Complete MCP protocol support
3. **View Logs**
- The application interface will display real-time logs
- Including server status, tool calls, and other information
## Version Compatibility Description
### Network and TLS Issues
If encountering the following error:
```
Could not GET 'https://repo.maven.apache.org/maven2/...'.
The server may not support the client's requested TLS protocol versions: (TLSv1.2, TLSv1.3)
```
**Solution:**
1. **Check Network Connection**
- Ensure the network connection is normal
- Check firewall settings
2. **Use Stable Version**
- The project uses Kotlin 1.9.22 (stable version)
- Android Gradle Plugin 8.1.4
- Gradle 8.2
3. **Clean and Rebuild**
```bash
# Windows
debug_build.bat
# Linux/Mac
chmod +x debug_build.sh
./debug_build.sh
```
4. **Manual Cleanup**
```bash
./gradlew clean
./gradlew build --stacktrace
```
### Kotlin Version Compatibility
The project is configured with forced version resolution to avoid version conflicts:
- Kotlin 1.9.22
- Kotlinx Coroutines 1.7.3
- Kotlinx Serialization 1.6.2
### Dependency Conflict Resolution
If encountering dependency conflicts, the project has configured:
- Forced version resolution strategy
- Exclusion of conflicting transitive dependencies
- Explicitly specify compatible versions
## Example Tools
The application has the following example tools built-in:
### 1. Get Device Information (`get_device_info`)
```json
{
"name": "get_device_info",
"description": "Get Android device information"
}
```
### 2. Get Current Time (`get_current_time`)
```json
{
"name": "get_current_time",
"description": "Get current time"
}
```
### 3. System Information Resource
- URI: `android://system/info`
- Provides detailed Android system information
### 4. Device Analysis Tips
- Name: `analyze_device`
- Used for analyzing device performance and status
## Custom Development
### Add New Tools
Add in the `setupTools()` method in `McpServerManager.kt`:
```kotlin
server.addTool(
name = "your_tool_name",
description = "Tool description"
) { request ->
// Tool logic
CallToolResult.success(
content = listOf(
TextContent(text = "Result content")
)
)
}
```
### Add New Resources
Add in the `setupResources()` method:
```kotlin
server.addResource(
uri = "your://resource/uri",
name = "Resource name",
description = "Resource description",
mimeType = "application/json"
) { request ->
// Resource logic
ReadResourceResult(contents = listOf(...))
}
```
## Troubleshooting
### Kotlin Version Compatibility Error
If encountering the following error:
```
Class 'io.modelcontextprotocol.kotlin.sdk.Implementation' was compiled with an incompatible version of Kotlin.
The actual metadata version is 2.1.0, but the compiler version 1.9.0 can read versions up to 2.0.0.
```
**Solution 1: Upgrade to Kotlin 2.1.0 (Recommended)**
1. Ensure the project uses Kotlin 2.1.0
2. Clean the project cache:
```bash
./gradlew clean
rm -rf .gradle
```
3. In Android Studio:
- File → Invalidate Caches and Restart
- Resync the project
**Solution 2: Use Compatible Version**
If upgrading has issues, use an alternative configuration:
```bash
# Backup current configuration
cp app/build.gradle.kts app/build.gradle.kts.backup
# Use compatible version configuration
cp app/build-fallback.gradle.kts app/build.gradle.kts
```
### Network Connection Issues
If encountering network connection errors:
1. **Use Network Repair Script**
```bash
# Windows
fix_network.bat
```
2. **Manual Cache Cleanup**
```bash
# Delete Gradle cache
rm -rf ~/.gradle/caches
rm -rf .gradle
# Rebuild
./gradlew clean build
```
3. **Offline Build**
```bash
./gradlew build --offline
```
### Common Issues
1. **Server Startup Failure**
- Check if the port is occupied
- Ensure network permissions are granted
- View application logs for detailed error information
2. **Dependency Conflict**
- Use forced version resolution (configured)
- Clean Gradle cache
- Resync the project
3. **Build Failure**
- Check network connection
- Try using a proxy or VPN
- Use an alternative configuration file
4. **SSE Plugin Conflict Resolved**
The project has fixed SSE plugin conflict issues:
- Use manually implemented SSE endpoint
- Do not rely on Ktor SSE plugin
- Avoid plugin duplicate installation errors
5. **MCP SDK API Error**
If encountering MCP SDK-related compilation errors:
- Ensure the correct Kotlin version is used (2.1.0)
- Clean the project cache and rebuild
- Check network connection to ensure dependencies are downloaded completely
### Version Compatibility Matrix
| MCP SDK | Kotlin | Android Gradle Plugin | Gradle |
|---------|--------|----------------------|--------|
| 0.5.0 | 2.1.0+ | 8.2.0+ | 8.4+ |
| 0.4.0 | 1.9.0+ | 8.1.0+ | 8.2+ |
| 0.3.0 | 1.9.0+ | 8.0.0+ | 8.0+ |
### Log Debugging
The application provides detailed log information:
- Server startup/stop status
- Tool call records
- Error information and stack trace
- Network connection status
## License
MIT License
## Contribution
Feel free to submit Issues and Pull Requests!
