feat(setup): import selected local MCP entries

[mohanagy]

Summary

• add an explicitly selected, no-secret import path for one existing local stdio MCP entry
• expose the same typed importer through miftah setup and the first-run Console
• require a finite static launch grammar, exact package versions, verified source-file reads, and safe-default policy
• preserve no-source-value error/audit/config boundaries and direct unsupported entries to advanced manual setup
• document the CLI and Console paths with regression coverage

Part of #204; this does not close the shared setup-wizard epic.

Security impact

The importer never launches or modifies the source client entry. It accepts only an explicit selected local stdio entry through a finite static launch grammar, rejects credential-shaped and dynamic input, and never writes pasted document values to configuration, audit records, browser storage, or HTTP errors. Imported configurations start read-only and treat unknown tools as destructive.

Validation

Passed locally on 9c91a3eeda99909c960642e7008c3cc15ce72640:

• npm test
• npm run test:core
• npm run test:coverage
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package

Focused local security and maintainability reviews found no remaining blocker. Current-head CI and CodeRabbit review are in progress.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 13 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ff1f02c8-9619-4c0a-bd90-8f51a11225d6

📥 Commits

Reviewing files that changed from the base of the PR and between 9c91a3e and 6e8b0d7.

📒 Files selected for processing (4)

• README.md
• docs/cli.md
• src/setup/client-entry-import.ts
• tests/client-entry-import.test.ts

📝 Walkthrough

Walkthrough

Adds secure import of explicitly selected local MCP stdio entries through CLI setup and first-run console onboarding. Imported entries produce read-only configurations, reject remote or credential-shaped inputs, support bounded source reads, and expose dedicated validation, error, API, UI, documentation, and test coverage.

Changes

Client-entry import

Layer / File(s)	Summary
Secure entry validation and configuration conversion src/setup/client-entry-import.ts, src/setup/client-entry-import-file.ts, src/utils/errors.ts, src/cli/exit-codes.ts, tests/client-entry-import*.test.ts, tests/cli-exit-codes.test.ts	Validates bounded local configuration documents and verified source-file reads, rejects unsafe or credential-shaped launches, converts accepted entries into read-only configurations, and adds stable error coverage.
CLI import setup flow src/cli/parse.ts, src/cli/setup.ts, src/cli/setup-client-entry-import.ts, README.md, docs/cli.md, tests/cli-parse.test.ts, tests/setup-command.test.ts, tests/readme-product-contract.test.ts	Adds guided setup import flags, publishes imported configurations, renders client handoff snippets, rejects --verify and incompatible options, and documents the import contract.
Console onboarding integration src/console/console-application-service.ts, src/console/console-dashboard-application-service.ts, src/console/console-server.ts, src/console/console-assets.ts, docs/console-api.md, README.md, tests/console-*.test.ts	Adds a CSRF-protected bounded onboarding endpoint, first-run service delegation, pasted-entry UI, static-launch error mapping, and dashboard onboarding tests.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• [Onboarding] Build a shared CLI and Console MCP setup wizard #204 — Directly covers the shared CLI and Console local client-entry import setup path implemented here.

Possibly related PRs

• mohanagy/miftah#213 — Extends the same setup verification flow by making verification inapplicable to imported entries.
• mohanagy/miftah#183 — Extends the same local Console control API and its request/error handling framework.
• mohanagy/miftah#201 — Updates the README contract and related product documentation tested by this change.

Poem

I’m a bunny with a config to share,
A local stdio path, securely bare.
No secrets copied, no remote flight,
Just read-only profiles, tucked in right.
Static launches hop in the queue—
Miftah says “safe” with a carrot or two!

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately describes the main change: importing selected local MCP entries.
Description check	✅ Passed	The description includes the required Summary, Security impact, and Validation sections with relevant details.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/204-client-import

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/setup/client-entry-import.ts`:
- Around line 153-160: Update the packageRunners handling around packageArgument
so pnpm dlx and its pnpx alias are not validated as ordinary package-runner
launches; either remove pnpm from packageRunners or add an explicit dlx special
case before staticPackageArgument validation, while preserving existing behavior
for other runners.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d8fdceb8-3466-49b9-8c5e-d8fb238ba11b

📥 Commits

Reviewing files that changed from the base of the PR and between 326a6c6 and 9c91a3e.

📒 Files selected for processing (23)

• README.md
• docs/cli.md
• docs/console-api.md
• src/cli/exit-codes.ts
• src/cli/parse.ts
• src/cli/setup-client-entry-import.ts
• src/cli/setup.ts
• src/console/console-application-service.ts
• src/console/console-assets.ts
• src/console/console-dashboard-application-service.ts
• src/console/console-server.ts
• src/setup/client-entry-import-file.ts
• src/setup/client-entry-import.ts
• src/utils/errors.ts
• tests/cli-exit-codes.test.ts
• tests/cli-parse.test.ts
• tests/client-entry-import-file.test.ts
• tests/client-entry-import.test.ts
• tests/console-application-service.test.ts
• tests/console-dashboard-application-service.test.ts
• tests/console-server.test.ts
• tests/readme-product-contract.test.ts
• tests/setup-command.test.ts

[mohanagy]

Review note: the current-head CodeRabbit status is pass — Review rate limited. The prior actionable thread has been fixed in 6e8b0d7 and resolved, including additional regressions for the related shell-mode boundaries. I also completed an independent local security review of the finite runner grammar; it found no remaining concrete runner-shell bypass. This documents the rate-limit exception while current-head CI completes.

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.