# Moory

Moory is a self-hosted, security-hardened MCP bridge that lets Notion AI work with explicitly registered Git repositories and curated GitHub APIs. It includes guarded code changes, commits, pushes, issues, pull requests, Actions, logs, releases, secret scanning and audit logging.

## Quick setup

Install Moory on a fresh Ubuntu 24.04 server with one command:

```bash
curl -fsSL https://raw.githubusercontent.com/dalmaktube-creator/DV-Moory/main/install.sh | sudo bash
```

The installer asks for the data path, local port, public domain, GitHub authentication mode and first repository.

For personal use, choose **Quick Mode** and provide a fine-grained GitHub token limited to the repositories Moory should access.

After installation, open the control center with:

```bash
sudo moory
```

## Worker core

Moory keeps reasoning with the connected agent and moves deterministic repository work to the server.

- `worker_context` provides a compact repository overview or fixed-text code search.
- `detail=summary` minimizes routine output, `detail=evidence` includes nearby source context, and `detail=full` is an explicit escape hatch.
- Results are bounded and report truncation instead of silently hiding additional matches.
- `moory_capabilities` teaches connected agents when to escalate context and why summary alone is not edit evidence.
- `moory_tool_catalog` exposes compact `core`, `git`, and `github` profiles while keeping the full tool escape hatch.
- Repository file maps are cached by the exact commit SHA while worktree status remains live.
- `worker_benchmark` reports measured JSON bytes and calls without claiming exact token savings.
- `inspect_ci_failure` combines failed jobs with bounded, deduplicated, redacted error groups and nearby log context.
- `github_permission_diagnostics` probes safe read capabilities without mutating repositories.
- `validate_project` parses tracked Python, JSON, and TOML files without executing repository code.
- `apply_change_set` preflights tracked-file patches, runs static validation by default, and rolls back on validation failure.
- `release_readiness` reports branch, worktree, remote divergence, latest CI, changelog, and tag checks without mutation.

The original granular read tools remain available, so agents can always inspect exact files and line ranges when compact context is insufficient.

### Exact evidence and transactional changes

- `read_tracked_files` batches up to eight ranges with a shared character budget; failed or budget-exhausted ranges are explicit. Each successful range includes `sha256`, `truncated` and a `next_cursor`.
- `read_tracked_file` preserves UTF-8 content **including original line terminators**, except detected credentials, which are explicitly masked without shifting character offsets. Follow `next_cursor` with `expected_sha256`; content changes fail closed. Line/column cursors also resume within unusually long lines. Historical reads additionally return the commit and blob SHA.
- Pass `expected_head` and/or per-file `expected_sha256` to `apply_change_set`. Identity verification, preflight, application, validation and rollback share the same write lock. Regular text additions are supported and validated before success; renames, copies, binary patches and symlinks are not supported by this transactional tool.
- These SHA guards detect stale context, not independent processes writing outside Moory. Coordinate external Git/file writes separately. Legacy callers may omit the optional guards; the result explicitly reports whether guards were supplied.
- `inspect_ci_failure detail=evidence` scans the entire bounded archive but only returns bounded failure groups. `truncated` and `groups_omitted` disclose shortened evidence. Use its `full_evidence_request` with `github_get_actions_log`, then follow `next_cursor` to recover every character of the redacted source. A changed log SHA requires restarting rather than mixing snapshots.
- For log pagination use `start_offset=0`; the legacy default still requests a tail. Limits on archive members or expansion cause an explicit error, not a silently incomplete scan. Pagination currently re-downloads the archive; it is not a persistent snapshot store and expired GitHub logs remain unavailable.
- Compact MCP serialization removes JSON indentation only. It preserves values and structured output; it does not control client-side wrappers or promise a fixed token saving.
- Static validation parses code; it is **not** execution of the test suite. Real regressions run through `./scripts/test.sh` and GitHub CI. No arbitrary remote shell or implicit workflow dispatch is introduced; existing workflow confirmation gates remain unchanged.


## Research-derived safety and navigation

- Known credentials are masked before file pagination and at the outbound text/structured-output boundary; redaction is explicit and original-byte SHA guards are retained.
- Tracked-file overview caches also fingerprint the index inventory, so staged additions/deletions do not leave a stale map.
- Optional operator settings `MOORY_TOOL_PROFILE=core|research|github|all` and `MOORY_READ_ONLY=1` filter actual registered tools; the default remains `all` for compatibility.
- `code_outline` provides read-only, SHA-guarded Python AST navigation without executing code or substituting a skeleton for edit evidence.
- Completed CI snapshots use a bounded in-memory cache with live authorization checks and backend-credential/run-revision partitioning.
- `server_diagnostics` reports build/schema identities and aggregate timing/byte/HTTP counters without payloads.

See [research-derived improvements](docs/RESEARCH-IMPROVEMENTS.md) for limits, policy configuration, security caveats and validation.

## GitHub coverage

Moory exposes curated tools for repository content, issues, pull requests, reviews, Actions runs, workflows, checks, commit statuses, artifacts, releases, deployments, environments, Actions variables, Pages, security alerts, advisories, supply-chain metadata, labels, milestones, discussions, merge queues, collaborators, rulesets and custom properties.

Known platform limits:

- Repository custom property values require organization-owned repositories.
- GitHub Packages endpoints reject GitHub App installation tokens and need a classic token with package scopes.
- Classic Projects endpoints are retired and intentionally unsupported.
- Delete, archive and visibility changes are intentionally not implemented.

## Security model

- Registered repository and branch allowlist
- No arbitrary shell or raw GitHub API endpoint
- No force-push, history rewrite or repository deletion
- Agent-supplied operation markers for merge, review, workflow mutations and release publication. Once the user has explicitly requested an operation, the agent fills `confirmation` internally; the user need not repeat a magic phrase. Ambiguous intent/target/scope still requires clarification, and all technical safeguards remain enforced.
- Secret detection before writes
- Short-lived GitHub App tokens in Hardened Mode
- Dedicated SSH deploy key per repository
- Sanitized audit logs
- Hardened systemd sandbox
- Local-only MCP listener behind HTTPS Bearer authentication

## Supported platform

- Ubuntu 24.04
- Python 3.12+
- systemd
- Caddy for public HTTPS

## Documentation

- `docs/INSTALL-FA.md` — Persian installation guide
- `docs/SECURITY-FA.md` — security guide
- `docs/ARCHITECTURE-FA.md` — architecture
- `docs/MIGRATION-FA.md` — migration
- `SECURITY.md` — vulnerability reporting

## License

Apache License 2.0.


## Public HTTPS port

New installations default to public HTTPS port **8443**, independently of the
local-only MCP listener **127.0.0.1:8787**. Use **9443** as an alternative when
8443 is occupied. The installer checks both TCP and UDP on the chosen public
port and refuses another service's listener; it does not stop that service.
The endpoint is `https://YOUR_DOMAIN:8443/mcp`. Custom-port acceptance by the
MCP client must be verified during connection setup.

Keep DNS pointed at the server and **TCP 80** reachable for automatic ACME
HTTP-01 certificate issuance and renewal, plus **TCP 8443** (or the selected
port) for MCP. Also configure the provider firewall if present. MCP itself
does not require UDP. Existing Caddy global options and unrelated tunnels on
UDP 443 are preserved; this setup does not enable HTTP/3 in a shared config.

The public port is saved as `MOORY_HTTPS_PORT`. Existing installations without
that setting retain port 443 until explicitly changed. The management menu,
connection URL, and end-to-end health check all use the saved public port.
To configure explicitly: `sudo moory-configure-caddy YOUR_DOMAIN 8787 8443`.