android-mcp-server by alguojian - MCP Server

Android MCP Server

一个基于 MCP Kotlin SDK 的 Android 服务器应用，使用 SSE (Server-Sent Events) 传输协议。

功能特性

🚀 完整 MCP 服务器 - 完整的 Model Context Protocol 服务器实现
📡 SSE 传输协议 - 使用 Server-Sent Events 进行实时通信
🎨 Material Design - 现代化的 Android UI 设计
🔧 丰富工具集 - 设备信息、时间查询等示例工具
📚 资源管理 - 系统信息等资源访问
💡 智能提示 - 设备分析等提示功能
📱 后台服务 - 前台服务确保服务器持续运行
📊 实时日志 - 查看服务器运行状态和日志

技术栈

Kotlin 2.1.0 - 现代化的编程语言
MCP Kotlin SDK 0.5.0 - 官方 MCP SDK
Ktor - 高性能 HTTP 服务器
Android Jetpack - 现代 Android 开发组件
Material Design 3 - 最新的设计系统

快速开始

环境要求

Android Studio Hedgehog | 2023.1.1 或更高版本
Android SDK API 24 (Android 7.0) 或更高版本
Kotlin 2.1.0
Gradle 8.4

安装步骤

克隆项目

git clone <repository-url>
cd mcp-kotlin

在 Android Studio 中打开项目
- 打开 Android Studio
- 选择 "Open an existing project"
- 选择项目目录
同步 Gradle
- Android Studio 会自动提示同步
- 等待依赖下载完成
运行应用
- 连接 Android 设备或启动模拟器
- 点击 "Run" 按钮

快速测试

构建项目
- Build → Clean Project
- Build → Rebuild Project
运行应用
- 运行应用
- 启动服务器
- 测试 MCP 连接

使用方法

启动服务器
- 打开应用
- 配置端口号（默认 8080）
- 设置服务器名称
- 点击 "启动服务器"
连接测试
- 主页：http://localhost:8080/
- SSE 端点：http://localhost:8080/sse
- 状态查询：http://localhost:8080/status
- 完整 MCP 协议支持
查看日志
- 应用界面会显示实时日志
- 包括服务器状态、工具调用等信息

版本兼容性说明

网络和 TLS 问题

如果遇到以下错误：

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)

解决方案：

检查网络连接
- 确保网络连接正常
- 检查防火墙设置
使用稳定版本
- 项目使用 Kotlin 1.9.22（稳定版本）
- Android Gradle Plugin 8.1.4
- Gradle 8.2

清理和重建

# Windows
debug_build.bat

# Linux/Mac
chmod +x debug_build.sh
./debug_build.sh

手动清理

./gradlew clean
./gradlew build --stacktrace

Kotlin 版本兼容性

项目配置了强制版本解析来避免版本冲突：

Kotlin 1.9.22
Kotlinx Coroutines 1.7.3
Kotlinx Serialization 1.6.2

依赖冲突解决

如果遇到依赖冲突，项目已配置：

强制版本解析策略
排除冲突的传递依赖
明确指定兼容版本

示例工具

应用内置了以下示例工具：

1. 获取设备信息 (`get_device_info`)

{
  "name": "get_device_info",
  "description": "获取 Android 设备信息"
}

2. 获取当前时间 (`get_current_time`)

{
  "name": "get_current_time", 
  "description": "获取当前时间"
}

3. 系统信息资源

URI: android://system/info
提供详细的 Android 系统信息

4. 设备分析提示

名称: analyze_device
用于分析设备性能和状态

自定义开发

添加新工具

在 McpServerManager.kt 中的 setupTools() 方法中添加：

server.addTool(
    name = "your_tool_name",
    description = "工具描述"
) { request ->
    // 工具逻辑
    CallToolResult.success(
        content = listOf(
            TextContent(text = "结果内容")
        )
    )
}

添加新资源

在 setupResources() 方法中添加：

server.addResource(
    uri = "your://resource/uri",
    name = "资源名称",
    description = "资源描述",
    mimeType = "application/json"
) { request ->
    // 资源逻辑
    ReadResourceResult(contents = listOf(...))
}

故障排除

Kotlin 版本兼容性错误

如果遇到以下错误：

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.

解决方案 1：升级到 Kotlin 2.1.0（推荐）

确保项目使用 Kotlin 2.1.0
清理项目缓存：
```
./gradlew clean
rm -rf .gradle
```
在 Android Studio 中：
- File → Invalidate Caches and Restart
- 重新同步项目

解决方案 2：使用兼容版本 如果升级有问题，可以使用备用配置：

# 备份当前配置
cp app/build.gradle.kts app/build.gradle.kts.backup

# 使用兼容版本配置
cp app/build-fallback.gradle.kts app/build.gradle.kts

网络连接问题

如果遇到网络连接错误：

使用网络修复脚本
```
# Windows
fix_network.bat
```

手动清理缓存

# 删除 Gradle 缓存
rm -rf ~/.gradle/caches
rm -rf .gradle

# 重新构建
./gradlew clean build

离线构建
```
./gradlew build --offline
```

常见问题

服务器启动失败
- 检查端口是否被占用
- 确保网络权限已授予
- 查看应用日志获取详细错误信息
依赖冲突
- 使用强制版本解析（已配置）
- 清理 Gradle 缓存
- 重新同步项目
构建失败
- 检查网络连接
- 尝试使用代理或 VPN
- 使用备用配置文件
SSE 插件冲突已解决 项目已修复 SSE 插件冲突问题：
- 使用手动实现的 SSE 端点
- 不依赖 Ktor SSE 插件
- 避免插件重复安装错误
MCP SDK API 错误 如果遇到 MCP SDK 相关的编译错误：
- 确保使用正确的 Kotlin 版本（2.1.0）
- 清理项目缓存并重新构建
- 检查网络连接，确保依赖下载完整

版本兼容性矩阵

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+

日志调试

应用提供详细的日志信息：

服务器启动/停止状态
工具调用记录
错误信息和堆栈跟踪
网络连接状态

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！