@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/PRIVACY.md

@@ -0,0 +1,21 @@
+# MCP Device Privacy
+
+MCP Device runs local file, process, and editing operations on a user-owned computer and connects outbound to the configured MCP gateway.
+
+The runtime does not send product analytics, telemetry, survey events, or remote feature-flag requests. Local execution data is transferred to the configured gateway only as required to execute authenticated tool calls and report bounded device status/usage metadata.
+
+Device state is stored under `~/.mcp-device/`. Package updates may contact the package registry when an authenticated owner requests a supported self-update.
+
+## Device-local context (1.0.11 development)
+
+Context is stored under the device state root in `context/`, with an owner registry, repository SQLite databases (including WAL/SHM), and minimal unscoped metadata. Retained payloads, search documents, and derived activity relations are local; there is no context provider or analytics upload. Authenticated remote search/read necessarily returns the selected bounded evidence through the gateway to the requesting client. The context gateway forwarding seam does not persist or cache evidence; deployment-wide logging policy remains the operator's responsibility.
+
+The canonical observer covers supported public device calls when explicitly approved. It does not read agent transcripts or observe every native editor/shell action. Checkpoint summaries and test claims are reported, not observed traces. Missing capture and unknown-after-restart outcomes are surfaced as coverage gaps; side effects are never replayed to fill a gap.
+
+Before persistence, payloads pass through bounded UTF-8 redaction. Patterns cover private keys, bearer tokens, common credential assignments and known token prefixes; selected credential paths, binary and oversized payloads are excluded/truncated. **This is best-effort pattern matching, not exhaustive secret detection.** Arbitrary unlabeled secrets, sensitive prose and new credential formats may remain. Do not submit credentials or assume local evidence is safe to publish. Protect the state directory with OS permissions; SQLite files are not encrypted by this feature.
+
+Re-pairing seals the former owner namespace from default CLI, skill and MCP access; it does not delete old data. No silent old-event eviction or per-turn maintenance is performed. Destructive administration is not available through the agent MCP catalog. Stop the runtime before an operator backup/removal of local state; do not copy only the main SQLite file while WAL is active. Legacy import preserves its source files.
+
+See [context documentation](docs/context.md) for scope, migration, source attribution and limitations.
+
+For the hosted service, server-side operational and security logs are governed by the deployment operator. Self-hosted deployments control their own gateway and logging policy.

package/README.md

@@ -1,8 +1,25 @@
 # MCP Device
 
-The gateway owns accounts, OAuth, device ownership, MCP tool contracts, routing, and usage aggregation. MCP Device owns local device identity, pairing, reconnect lifecycle, bounded execution, background registration, and local status.
+MCP Device provides local identity, pairing, reconnect, bounded execution, background registration and status. In source 1.0.12, `mcp-device server` also runs the account/OAuth control plane and one mandatory local runtime through the same Device Core used by remote Devices. `mcp-device start` keeps the existing Device-only behavior.
 
-## Install
+## 1.0.12 source candidate
+
+The v12 increment remains the `@hcu-lab.me/mcp-device` product. Its public package is Core-only: native execution, a generic versioned PluginHost, normal localhost account/pairing, and stopped-state backup/migration. P1 `logs` and Context remain Core compatibility surfaces, not the optional Palace plugin. Core installs and starts no Palace code or Skill integration automatically.
+
+Palace is built separately from the same canonical source with `npm run build:palace`. Its package, `@hcu-lab.me/palace`, contains `palace.plugin.json`, the Palace executable and its Skill installer. Register that installed manifest explicitly with `mcp-device plugins install /absolute/path/to/palace.plugin.json --enable`. Explicit install/enable survives restart while its separately installed entry remains available. Existing automatic distribution-enabled Palace records remain retained but inert until explicitly enabled; disabled/uninstalled records and private data are preserved. Core updates do not install, repin or upgrade Palace. Legacy `--plugin-policy bundled|core-first` values are compatibility inputs only and cannot restore the old bundled default.
+
+An old bundled Palace entry disappears when its Device package is replaced by Core. Retaining its registry/data does not keep that code operational: automatic records remain suppressed, and previously explicit records can fault on the missing entry. Continuing Palace is optional: separately install its reviewed package, have the operator stop the runtime, upgrade the existing registration to the separate manifest, then explicitly enable it. See [migration steps](docs/v12-platform.md#migrating-an-old-bundled-palace-installation). Core never downloads or migrates Palace automatically; preserve the existing state root and identity.
+
+See the [v12 platform guide](docs/v12-platform.md), [acceptance evidence](specs/008-v12-platform/ACCEPTANCE.md), [Device parity inventory](specs/008-v12-platform/device-parity.json), and [Gateway parity inventory](specs/008-v12-platform/gateway-parity.json). Source and isolated-package acceptance do not imply npm publication or production deployment.
+
+```text
+mcp-device start
+mcp-device device status
+mcp-device server --runtime-dir <isolated-state> --host 127.0.0.1 --port 8104
+mcp-device plugins --runtime-dir <isolated-state> list
+```
+
+## Historical installation example
 
 ```powershell
 npm install -g @hcu-lab.me/mcp-device@1.0.10
@@ -11,6 +28,44 @@ mcp-device install
 mcp-device status
 ```
 
+## 1.0.11 source compatibility
+
+Device source v1.0.11 is available on GitHub `main`, and requires Node **>=22.13.0**, including built-in `node:sqlite` with FTS5. Upgrade Node before using this source; no external SQLite npm driver is required. The 1.0.10 npm installation example above is historical: source delivery alone does **not** establish that 1.0.11 was published on npm or deployed.
+
+## Log-first memory search (source/P1)
+
+The new opt-in local CLI searches **existing Pi/Codex/MCP sessions and logs**, without enabling Context live capture/observer. See [log search commands and limitations](docs/log-palace.md).
+
+```text
+mcp-device logs discover
+mcp-device logs add <file-or-dir> --format auto
+mcp-device logs index
+mcp-device logs search --query "timeout reconnect" --limit 5
+mcp-device logs read --ref <ref>
+mcp-device logs graph --ref <ref>
+```
+
+These commands are available after building this source; they do **not** imply npm publication, production deployment, Wiki Palace or automatic skill learning.
+
+## Device-local context
+
+```text
+mcp-device context status --cwd . --json
+mcp-device context search --cwd . --query "gateway reconnect" --json
+mcp-device context read --cwd . --ref <evidence-ref> --json
+mcp-device context sync --cwd . --json
+```
+
+Search/read/status never run indexing automatically. Run sync selectively when freshness matters; verify current source separately. The CLI operates on the local state host without a gateway. Permission denial never triggers a remote fallback.
+
+The six gated MCP schemas are `local_status`, `local_search`, `local_read`, `local_graph`, `local_index` and `local_wiki`; public registration/live capture require valid runtime approval. Wiki is disabled. Source schemas: [`src/context/tool-contract.ts`](src/context/tool-contract.ts). Portable skill: [`skills/mcp-device-context/SKILL.md`](skills/mcp-device-context/SKILL.md); explicit client loading is supported, universal automatic discovery is not claimed.
+
+See [context commands, migration and limitations](docs/context.md) and [privacy](PRIVACY.md). Phase 9 acceptance evidence is under `evidence/context/`. GitHub source delivery does **not** authorize npm publication, tagging, SOC approval or production Context enablement.
+
+## Current status
+
+[**Device/Gateway status and active tasks**](docs/STATUS.md) · [Historical DONE/outdated material](docs/ARCHIVE.md). Source commit, published package and live Gateway tool catalog must be verified separately.
+
 ## Commands
 
 ```text

package/SECURITY.md

@@ -0,0 +1,67 @@
+# Security Policy
+
+## Security Model
+
+MCP Device is a privileged local automation tool. It lets an AI client you authorize read and write files and execute terminal commands on your machine. That capability is the point of the product — not a flaw.
+
+Because it can run arbitrary terminal commands, MCP Device should be understood as an **amplifier of whatever the connected AI client asks it to do**. Its built-in restrictions are **safety guardrails that reduce accidental or unintended actions**, not a security sandbox that can contain a malicious or compromised client.
+
+### Core assumption
+
+MCP Device assumes the connected AI client — and the account driving it — is **trusted and uncompromised**. It executes requested actions and does not attempt to determine whether a request originates from a genuine user, from prompt injection, or from a compromised AI account. Protecting the integrity of that client and account is part of the overall security model and is the user's responsibility.
+
+If the AI client should never be able to reach the rest of your machine, that guarantee can only come from OS-level isolation (see below).
+
+## What the built-in controls do
+
+| Control | Purpose | Security boundary? |
+|---------|---------|--------------------|
+| Allowed directories | Reduce accidental file access | No |
+| Command blocklist | Reduce accidental execution | No |
+| Symlink traversal prevention | Block a class of accidental path escapes | No |
+| Docker / VM isolation | Contain the tool to an isolated environment | Yes |
+
+Terminal command execution is a first-class feature. Because it can launch arbitrary programs, path-based and command-based restrictions can be circumvented by design — for example via shell substitution, absolute paths, or invoking another interpreter. These controls are advisory: they make common mistakes less likely; they are not a boundary against a client that is actively trying to escape them.
+
+## Recommended deployment for stronger isolation
+
+For any workload where the AI client must not access the wider machine, run MCP Device inside an isolated environment:
+
+- **Docker** with selective folder mounting (see the [Docker installation section](README.md#option-6-docker-installation-🐳-⭐-auto-updates-no-nodejs-required))
+- A **virtual machine**, dev container, or a separate/dedicated workstation
+
+Additional practical steps:
+
+- Enable MFA on the AI accounts you connect
+- Only connect AI clients you trust; remove ones you no longer use
+- Scope work to project-specific directories rather than your whole home folder
+- Review generated commands when the context warrants it
+
+## Known limitations
+
+- Directory restrictions are guardrails, not sandboxing — terminal commands can reach files outside `allowedDirectories`.
+- The command blocklist can be circumvented via substitution, absolute paths, or alternate interpreters.
+- MCP Device does not protect against a compromised AI account or prompt injection reaching a trusted client. For that threat model, use OS-level isolation.
+
+## License and responsibility
+
+MCP Device is free, open-source software released under the MIT License. As is standard for MIT-licensed software, it is provided "as is," without warranty, and you are responsible for how you deploy and secure it in your environment. This security model describes how the tool is designed to behave; it does not transfer responsibility for your accounts, machines, or connected AI clients to the project.
+
+## Reporting a Vulnerability
+
+We welcome responsible disclosure and review all reported security issues.
+
+1. **Open a GitHub issue** with technical details and, if possible, a proof of concept.
+2. **Label it security-related** for visibility.
+3. **Request attribution** if you'd like to be credited.
+
+If you'd prefer not to disclose publicly, reach out via Discord to arrange private disclosure. We acknowledge reports, assess severity and impact, and prioritize fixes accordingly.
+
+## Contact
+
+- **GitHub Issues**: https://github.com/Hiroshimeow/agent-mcp-device/issues
+- **Discord Community**: https://discord.gg/kQ27sNnZr7
+
+---
+
+*Last updated: July 2026*

package/config/revoked-approvals.json

@@ -0,0 +1 @@
+[]

package/control-plane/config/mcp-servers.example.toml

@@ -0,0 +1,52 @@
+# Unified MCP gateway config example.
+# Keep secrets and machine-specific paths out of Git; use environment variables
+# and runtime overlays for private values.
+
+[server]
+name = "agent-mcp-gateway"
+title = "MCP Gateway"
+description = "Remote MCP gateway for filesystem, shell, device routing, optional skills, and external MCP upstreams."
+instructions = "Use filesystem tools for file content, shell/process tools for terminal workflows, and list_devices for remote machines. Native Skills clients use the MCP Skills extension; other clients may use skill_catalog and load_skill."
+
+[surface]
+mode = "agent"
+
+[trusted_roots]
+# Generic trusted paths do not become routable projects automatically.
+# Put machine-specific project routes in a private/runtime overlay, for example:
+# { path = "/srv/app", project_id = "app", display_name = "App", device_id = "device-id" }
+roots = ["${repoRoot}"]
+
+[openai_tunnel]
+enabled = false
+command = "tunnel-client"
+profile = "default"
+
+[external_mcp]
+enabled = true
+fail_gateway_on_startup_error = false
+catalog_cache = "startup"
+exposure_mode = "hybrid"
+eager_schema_budget_bytes = 24576
+eager_allowlist = []
+startup_timeout_sec = 30.0
+shutdown_timeout_sec = 5.0
+default_enabled = false
+
+[mcp_servers.context7]
+enabled = false
+url = "https://mcp.context7.com/mcp"
+
+[mcp_servers.exa]
+enabled = false
+url = "https://mcp.exa.ai/mcp"
+
+[mcp_servers.deepwiki]
+enabled = false
+url = "https://mcp.deepwiki.com/mcp"
+
+[mcp_servers.eslint]
+enabled = false
+preset = "eslint"
+
+# Add optional upstreams with enabled = false, then opt in explicitly.

package/control-plane/config/mcp-servers.toml

@@ -0,0 +1,52 @@
+# Unified MCP gateway config example.
+# Keep secrets and machine-specific paths out of Git; use environment variables
+# and runtime overlays for private values.
+
+[server]
+name = "mcp-device"
+title = "MCP Device"
+description = "Remote MCP gateway for filesystem, shell, device routing, optional skills, and external MCP upstreams."
+instructions = "Use filesystem tools for file content, shell/process tools for terminal workflows, and list_devices for remote machines. Native Skills clients use the MCP Skills extension; other clients may use skill_catalog and load_skill."
+
+[surface]
+mode = "agent"
+
+[trusted_roots]
+# Generic trusted paths do not become routable projects automatically.
+# Put machine-specific project routes in a private/runtime overlay, for example:
+# { path = "/srv/app", project_id = "app", display_name = "App", device_id = "device-id" }
+roots = ["${repoRoot}"]
+
+[openai_tunnel]
+enabled = false
+command = "tunnel-client"
+profile = "default"
+
+[external_mcp]
+enabled = true
+fail_gateway_on_startup_error = false
+catalog_cache = "startup"
+exposure_mode = "hybrid"
+eager_schema_budget_bytes = 24576
+eager_allowlist = []
+startup_timeout_sec = 30.0
+shutdown_timeout_sec = 5.0
+default_enabled = false
+
+[mcp_servers.context7]
+enabled = false
+url = "https://mcp.context7.com/mcp"
+
+[mcp_servers.exa]
+enabled = false
+url = "https://mcp.exa.ai/mcp"
+
+[mcp_servers.deepwiki]
+enabled = false
+url = "https://mcp.deepwiki.com/mcp"
+
+[mcp_servers.eslint]
+enabled = false
+preset = "eslint"
+
+# Add optional upstreams with enabled = false, then opt in explicitly.