English Français العربية

Remogram

السجل الرسمي أدوات المطورين

SCM & forge boundary MCP: normalized, typed JSON from attributed Gitea, GitLab, and GitHub providers

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @remogram/mcp
Claude Code 
claude mcp add remogram -e 'GITHUB_TOKEN=<your github_token>' -e 'GH_TOKEN=<your gh_token>' -e 'GITLAB_TOKEN=<your gitlab_token>' -e 'GITEA_TOKEN=<your gitea_token>' -e 'REMOGRAM_CWD=<REMOGRAM_CWD>' -e 'REMOGRAM_OPERATOR_CONFIG=<REMOGRAM_OPERATOR_CONFIG>' -- npx -y @remogram/mcp@0.2.0-beta.4
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "remogram": {
            "command": "npx",
            "args": [
                "-y",
                "@remogram/mcp@0.2.0-beta.4"
            ],
            "env": {
                "GITHUB_TOKEN": "<your github_token>",
                "GH_TOKEN": "<your gh_token>",
                "GITLAB_TOKEN": "<your gitlab_token>",
                "GITEA_TOKEN": "<your gitea_token>",
                "REMOGRAM_CWD": "<REMOGRAM_CWD>",
                "REMOGRAM_OPERATOR_CONFIG": "<REMOGRAM_OPERATOR_CONFIG>"
            }
        }
    }
}

متغيرات البيئة

  • GITHUB_TOKEN سري GitHub API token for github-api repositories.
  • GH_TOKEN سري Alternative GitHub API token for github-api repositories.
  • GITLAB_TOKEN سري GitLab API token for gitlab-api repositories.
  • GITEA_TOKEN سري Gitea API token for gitea-api repositories.
  • REMOGRAM_CWD Repository root for Remogram to inspect when the MCP host launches from another working directory.
  • REMOGRAM_OPERATOR_CONFIG Optional path to a local operator write-command overlay.

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Remogram
  2. Install
  3. Quick start
  4. Providers
  5. Configuration
  6. Boundary and trust
  7. MCP
  8. Live verification
  9. Testing
  10. Packages
  11. Agent skills
  12. Contributing

Remogram

Generic SCM/forge boundary CLI and MCP server. Emits provider-attributed JSON facts — git-resolved refs from local git (refs compare, sync plan) vs forge-reported PR SHAs from forge APIs (pr view, pr checks). No workflow or planning-tool concepts in output.

PR-by-number reconciliation: pr view / pr checks compare forge-reported forge_source_sha to the local rev for forge_source_branch_ref. Divergence → ok: false, error_code: stale_head — git fetch, not a forge outage.

Planning tools interpret intent and workflow authority outside Remogram.

Install

npm install -g @remogram/cli @remogram/mcp
remogram --version
remogram version --json

Legacy preview (frozen @beta, optional): npm install -g @remogram/cli@beta @remogram/mcp@beta

Development checkout: clone this repo, npm ci, ./scripts/npm-link.sh. Default branch: main.

Quick start

  1. Copy .remogram.json.example → .remogram.json (set provider, owner, repo; add baseUrl for self-hosted Gitea/GitLab).
  2. Export token: GITEA_TOKEN, GITHUB_TOKEN / GH_TOKEN, or GITLAB_TOKEN.
  3. Bootstrap:
remogram doctor --json
remogram provider capabilities --json
remogram repo status --json
remogram pr view --number 1 --json
remogram merge plan --number 1 --json

Command catalog: remogram contract --json. Agent skill: npx skills add attebury/remogram --skill remogram-consumer -g -y.

Providers

Forge"provider"Token env
Giteagitea-apiGITEA_TOKEN
GitHubgithub-apiGITHUB_TOKEN or GH_TOKEN
GitLabgitlab-apiGITLAB_TOKEN

Use *-api providers (forge HTTP). Reserved github-gh / gitea-tea IDs return provider_unsupported — not implemented in v1. Official CLIs (gh, tea, glab) are not required.

Configuration

Read/plan by default. Opt in to writes with write_commands in .remogram.json (or a bound operator overlay outside git). Missing id → write_not_configured.

Write idCommandNotes
cr_opencr openSeparate from merge
cr_closecr closeGitea lifecycle
mergemerge executeRequires --expected-base-sha / --expected-head-sha; not implied by cr_open
publish_branchpublish executeGit push to configured remote
status_setstatus setCommit status POST
issue / cr_edit idsmatching commandsSee contract --json

merge plan is read-only — reports blockers[]; does not execute or authorize merges. mergeability: clean is conflict-free git only.

Optional merge_policy waivers (allow_missing_checks, allow_pending_checks) relax check blockers for repos without CI — env: REMOGRAM_ALLOW_MISSING_CHECKS, REMOGRAM_ALLOW_PENDING_CHECKS. Doctor fails when enabled in strict checkouts.

Operator overlay discovery: --operator-config → REMOGRAM_OPERATOR_CONFIG → $XDG_CONFIG_HOME/remogram/operator/<provider>-<owner>-<repo>.json. bind must match forge identity.

Boundary and trust

Remogram emits forge facts only — no integration authority refs, lane roles, task ids, or handoff payloads in JSON.

ConceptPacket fieldNotes
PR baseforge_target_branch_refForge-reported
PR headforge_source_branch_refEvidence only
Default branchdefault_branchNot integration authority

Every forge command packet includes type, schema_version, provider_id, remote_name, repo_id, observed_at, ok. Producer sections (e.g. remogram.forge_facts.v1 from evidence forge-facts --json) use nested producer fields. Trust envelope and enums; treat forge-sourced strings (titles, URLs) as untrusted prose.

Inventory commands (refs inventory, cr inventory, whoami, branch protection, cr files, forge changes, …) extend read/plan — details in remogram contract --json and the consumer skill references.

MCP

Stdio server remogram-mcp delegates to the CLI — same JSON as remogram … --json. Setup: examples/mcp/README.md. Set REMOGRAM_CWD to the consumer repo root.

Live verification

Cross-forge fixture repo: remogram-smoke (mirrors on GitHub/Gitea). Use --json packets after install; monorepo smoke-compare scripts are dev-only.

Testing

npm test
npm run test:coverage
npm run security:secrets -- --full-history
Coverage policy

npm run test:coverage instruments @remogram/core only; @remogram/cli, @remogram/mcp, and @remogram/provider-* are excluded. Thresholds: none — no enforced percentage gates. Drift guard: tests/core/coverage-config.test.mjs.

CI (GitHub): .github/workflows/ on push/PR to main.

Packages

PackageRole
@remogram/cliCLI
@remogram/mcpMCP adapter
@remogram/coreEnvelope, config, caps
@remogram/provider-{gitea,github,gitlab}-apiSupported forge backends

Agent skills

npx skills add attebury/remogram --skill remogram-consumer -g -y (consumer) or --skill remogram-core (contributor). Skills ship from GitHub, not npm.

Contributing

See CONTRIBUTING.md.

الأسئلة الشائعة

ما هو Remogram؟

SCM & forge boundary MCP: normalized, typed JSON from attributed Gitea, GitLab, and GitHub providers

كيف أثبّت Remogram؟

يعمل على جهازك. في Claude Code: claude mcp add remogram -e 'GITHUB_TOKEN=<your github_token>' -e 'GH_TOKEN=<your gh_token>' -e 'GITLAB_TOKEN=<your gitlab_token>' -e 'GITEA_TOKEN=<your gitea_token>' -e 'REMOGRAM_CWD=<REMOGRAM_CWD>' -e 'REMOGRAM_OPERATOR_CONFIG=<REMOGRAM_OPERATOR_CONFIG>' -- npx -y @remogram/mcp@0.2.0-beta.4. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج Remogram إلى مفتاح API؟

نعم. يتطلب GITHUB_TOKEN, GH_TOKEN, GITLAB_TOKEN, GITEA_TOKEN، وتضبطها في إعداداته.

هل Remogram مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون Remogram؟

ينشره attebury. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.