Skip to content

Migrate ALAS MCP Server to FastMCP 3.0 (Improved) #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Coldaine merged 10 commits into from
Jan 28, 2026
Merged

Migrate ALAS MCP Server to FastMCP 3.0 (Improved) #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
af6f124
feat: migrate MCP server to FastMCP 3.0 and add ALAS launcher wrapper
Coldaine Jan 27, 2026
682c1d7
test: add integration tests for FastMCP 3.0 server
Coldaine Jan 27, 2026
b680ba4
chore: add project-scoped Gemini MCP settings and apply ALAS core pat…
Coldaine Jan 27, 2026
9c084be
docs: add FastMCP 3.0 migration and architectural report
Coldaine Jan 27, 2026
4850909
docs: add dorm morale rotation and exercise optimization to backlog
Coldaine Jan 28, 2026
7d7f12a
docs: add dock inventory scanner to backlog
Coldaine Jan 28, 2026
9dc7943
docs: move feature ideas to dedicated doc, slim down todo
Coldaine Jan 28, 2026
50ce481
docs: add equipment outfitter idea to backlog
Coldaine Jan 28, 2026
ae32823
docs: add anti-scrap/retire safety guard to backlog
Coldaine Jan 28, 2026
f4c1004
chore: cleanup PR review findings
Coldaine Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .gemini/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"mcpServers": {
"alas-mcp": {
"command": "uv",
"args": [
"--directory",
"C:\\_projects\\ALAS\\agent_orchestrator",
Copy link

@kiloconnect kiloconnect bot Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: The settings file contains a hard-coded Windows path (C:\_projects\ALAS\agent_orchestrator) which may not work on other operating systems. Consider using relative paths or environment variables.

"run",
"alas_mcp_server.py",
"--config",
"alas"
]
}
}
}
13 changes: 13 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,19 @@ All notable changes to the ALAS AI Agent project.

## [Unreleased]

### Changed
- **MCP Server**: Migrated from hand-rolled JSON-RPC to FastMCP 3.0 framework
- ~30% code reduction (230 → 160 lines)
- Added full type safety via function signature validation
- Improved error handling (structured exception types → JSON-RPC error codes)
- All 7 tools remain functionally identical, now with better maintainability

### Added
- **Unit tests** (`test_alas_mcp.py`): 8 test cases covering all 7 MCP tools with mocked ALAS dependencies
- **Integration tests** (`test_integration_mcp.py`): Async tests exercising FastMCP `call_tool` interface
- **Server launcher** (`run_server.sh`): Shell script wrapper for running MCP server via `uv`
- **Project config** (`pyproject.toml`): Dependency management with FastMCP 3.0, dev group for pytest

### Fixed
- **StateMachine import**: `GeneralShop` renamed to `GeneralShop_250814` upstream (2025-08-14 shop UI update); aliased in `state_machine.py`
- **StateMachine wiring**: Added `state_machine` cached_property to `AzurLaneAutoScript` in `alas.py` — MCP server expected this property but it was never wired
Expand Down
29 changes: 21 additions & 8 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,19 +46,32 @@ The `alas_wrapped/` codebase is Python 3.7 legacy code with:

When extracting tools, expose the **behavior** not the implementation details.

## MCP Tool Status (Verified 2026-01-26)
## MCP Tool Status (Migrated to FastMCP 3.0, 2026-01-26)

All 7 MCP tools verified end-to-end against running MEmu emulator (127.0.0.1:21503).
All 7 MCP tools refactored from hand-rolled JSON-RPC to **FastMCP 3.0** framework.

**Improvements:**
- ✅ Type-safe function signatures (automatic schema generation)
- ✅ Structured error handling (ValueError, KeyError → proper JSON-RPC error codes)
- ✅ ~30% code reduction (230 → 160 lines)
- ✅ Unit testable (tools are plain Python functions)

| Tool | Category | Status | Notes |
|------|----------|--------|-------|
| `adb.screenshot` | ADB | Working | Returns base64 PNG. Requires `lz4` package. |
| `adb.tap` | ADB | Working | Taps (x, y) coordinate on device. |
| `adb.swipe` | ADB | Working | Swipes from (x1,y1) to (x2,y2). |
| `adb.screenshot` | ADB | Working | Returns base64 PNG. |
| `adb.tap` | ADB | Working | Type-safe coordinates (`x: int, y: int`). |
| `adb.swipe` | ADB | Working | Default duration 100ms. |
| `alas.get_current_state` | State | Working | Returns current page via StateMachine. |
| `alas.goto` | State | Working | Navigates to named page (e.g. `page_main`). |
| `alas.list_tools` | Tool | Working | Returns 9 registered domain tools. |
| `alas.call_tool` | Tool | Working | Invokes a registered tool by name. |
| `alas.goto` | State | Working | Raises `ValueError` if page unknown. |
| `alas.list_tools` | Tool | Working | Returns structured list. |
| `alas.call_tool` | Tool | Working | Invokes registered tool by name. |

### Launch Command
```bash
cd agent_orchestrator
uv run alas_mcp_server.py --config alas
```


### Environment Prerequisites

Expand Down
Loading