1 files changed, 150 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..54e9247
--- /dev/null
+++ b/README.md
@@ -0,0 +1,150 @@
+# Sailfish Devel MCP
+
+Host-side Model Context Protocol server for Sailfish OS development workflows.
+
+This first iteration is dependency-free: it implements MCP over stdio directly
+with Python's standard library and exposes typed tools around commands that are
+easy to get wrong during day-to-day Sailfish work.
+
+## Scope
+
+The server currently exposes tools for:
+
+- Sailfish device access over SSH
+- defaultuser session-bus calls
+- Lipstick screenshots
+- touchscreen discovery and tap/swipe injection
+- topmost window PID lookup
+- process map inspection
+- journal log reads
+- RPM copy/install on a device
+- system and user service management
+- Docker/mb2 RPM builds through the local `build-sailfishos` helper
+- Jolla OBS result and build-log lookup through `osc`
+- repository status and search under the configured git root
+- RPM spec metadata summaries
+- QML translation search and Sailfish ternary translation checks
+
+The committed defaults are deliberately generic. Device tools default to the
+placeholder SSH target `root@device`, the Sailfish user-session bus at
+`/run/user/100000/dbus/user_bus_socket`, `~/git` as the local source root, and
+the vendored build helper at
+`src/sailfish_devel_mcp/vendor/build_sailfishos.py`. Put a config file at
+`~/.config/sailfish-devel-mcp/config.json` or pass `--config` to provide your
+real device and OBS settings. Device entries can also carry the preferred
+user, architecture, and current release label. If an installed SDK is
+available, set `paths.local_sdk` to its `sdk-chroot` path; builds will use it
+when it has a target matching the requested release and architecture, otherwise
+they fall back to the coderus SDK image.
+
+## Running
+
+From a checkout:
+
+```sh
+/path/to/sailfish-devel-mcp/bin/sailfish-devel-mcp
+```
+
+To inspect the effective configuration:
+
+```sh
+/path/to/sailfish-devel-mcp/bin/sailfish-devel-mcp --dump-config
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "sailfish-devel": {
+      "command": "/path/to/sailfish-devel-mcp/bin/sailfish-devel-mcp"
+    }
+  }
+}
+```
+
+## Configuration
+
+Example:
+
+```json
+{
+  "default_device": "phone",
+  "devices": {
+    "phone": {
+      "ssh_target": "root@phone",
+      "username": "defaultuser",
+      "architecture": "aarch64",
+      "release": "live",
+      "user_bus_runtime_dir": "/run/user/100000",
+      "user_bus_address": "unix:path=/run/user/100000/dbus/user_bus_socket"
+    }
+  },
+  "paths": {
+    "git_root": "/home/you/git",
+    "ssh_config": "/home/you/.ssh/config",
+    "local_sdk": "/srv/mer/sdks/sfossdk/sdk-chroot",
+    "osc_api_alias": "your-obs-alias"
+  }
+}
+```
+
+## Tool Notes
+
+The server keeps local paths scoped to the configured git root and `/tmp` for
+tools that read or write files. Device access still uses SSH, so the usual SSH
+prompts, permissions, and command failures are surfaced as tool results.
+
+Mutating tools are annotated as non-read-only:
+
+- `sailfish_device_lipstick_screenshot`
+- `sailfish_device_touch`
+- `sailfish_device_user_bus_call`
+- `sailfish_device_install_rpm`
+- `sailfish_device_restart_service`
+- `sailfish_build_rpm`
+
+`sailfish_device_lipstick_screenshot` defaults to
+`~/Pictures/Screenshots/lipstick-<timestamp>.png` under `/home/<username>`,
+where `username` comes from the device config. Lipstick rejects screenshot save
+paths outside the home directory. When that directory is missing, the tool
+derives ownership with `stat -L`, creates `Pictures` as that owner/group with
+mode `775`, and creates `Pictures/Screenshots` as that owner and the
+`privileged` group with mode `755` when the group exists.
+
+`sailfish_device_touch` supports `discover`, `tap`, and `swipe`. Discovery
+prints `/proc/bus/input/devices` and can also run `evdev_trace -i` when
+`include_evdev_trace` is true. Tap and swipe auto-select a likely touchscreen
+input event device unless `input_device` is supplied. Coordinates are raw
+input/display coordinates, so pair this tool with a current screenshot when
+choosing points.
+
+`sailfish_build_rpm` can use a configured device's `architecture` and `release`
+as defaults when the call includes `device`. If `paths.local_sdk` is set, the
+build helper first checks the installed SDK targets. `live` uses the unversioned
+local target for the requested architecture, for example `aarch64`; a named
+release such as `5.0.0` uses a matching versioned local target such as
+`aarch64-5.0.0`. If the required target is not installed, the helper falls back
+to the release-specific coderus Docker SDK image. The wrapper image defaults to
+`sailfish-sdk-build-engine:$USER` and can be overridden with
+`SAILFISH_SDK_BUILD_ENGINE_IMAGE`.
+
+Read-only tools include the journal, topmost PID, process maps, OBS lookup,
+repo search, spec summary, and QML checks.
+
+## Smoke Test
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | /path/to/sailfish-devel-mcp/bin/sailfish-devel-mcp
+```
+
+## Development
+
+Run tests without installing the package:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests
+```