@nimrobo/mcporter-remote 0.1.0

package/dist/server-proxy.js

@@ -0,0 +1,342 @@
+import { createCallResult } from './result-utils.js';
+import { readSchemaCache, writeSchemaCache } from './schema-cache.js';
+const KNOWN_OPTION_KEYS = new Set(['tailLog', 'timeout', 'stream', 'streamLog', 'mimeType', 'metadata', 'log']);
+// defaultToolNameMapper converts camelCase property access into kebab-case tool names.
+function defaultToolNameMapper(propertyKey) {
+    if (typeof propertyKey !== 'string') {
+        throw new TypeError('Tool name must be a string when using server proxy.');
+    }
+    return propertyKey.replace(/([a-z\d])([A-Z])/g, '$1-$2').toLowerCase();
+}
+// canonicalizeToolName strips punctuation for loose matching of tool names.
+function canonicalizeToolName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+// isPlainObject narrows unknown values to plain object records.
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// createToolSchemaInfo normalizes schema metadata used for argument mapping.
+function createToolSchemaInfo(schemaRaw) {
+    if (!schemaRaw || typeof schemaRaw !== 'object') {
+        return undefined;
+    }
+    const schema = schemaRaw;
+    const propertiesRaw = schema.properties;
+    const propertyKeys = propertiesRaw && typeof propertiesRaw === 'object' ? Object.keys(propertiesRaw) : [];
+    const requiredKeys = Array.isArray(schema.required) ? schema.required : [];
+    const orderedKeys = [];
+    const seen = new Set();
+    for (const key of requiredKeys) {
+        if (typeof key === 'string' && !seen.has(key)) {
+            orderedKeys.push(key);
+            seen.add(key);
+        }
+    }
+    for (const key of propertyKeys) {
+        if (!seen.has(key)) {
+            orderedKeys.push(key);
+            seen.add(key);
+        }
+    }
+    return {
+        schema,
+        orderedKeys,
+        requiredKeys,
+        propertySet: new Set([...propertyKeys, ...requiredKeys]),
+    };
+}
+// applyDefaults merges JSON-schema default values into the provided arguments.
+function applyDefaults(meta, args) {
+    const propertiesRaw = meta.schema.properties;
+    if (!propertiesRaw || typeof propertiesRaw !== 'object') {
+        return args;
+    }
+    const result = isPlainObject(args) ? { ...args } : {};
+    for (const [key, value] of Object.entries(propertiesRaw)) {
+        if (value &&
+            typeof value === 'object' &&
+            'default' in value &&
+            result[key] === undefined) {
+            result[key] = value.default;
+        }
+    }
+    if (Object.keys(result).length === 0 && !isPlainObject(args)) {
+        return args;
+    }
+    return result;
+}
+// validateRequired ensures all schema-required fields are present before invocation.
+function validateRequired(meta, args) {
+    if (meta.requiredKeys.length === 0) {
+        return;
+    }
+    if (!isPlainObject(args)) {
+        throw new Error(`Missing required arguments: ${meta.requiredKeys.join(', ')}`);
+    }
+    const missing = meta.requiredKeys.filter((key) => args[key] === undefined);
+    if (missing.length > 0) {
+        throw new Error(`Missing required arguments: ${missing.join(', ')}`);
+    }
+}
+// createServerProxy returns a proxy that maps property access to MCP tool invocations.
+export function createServerProxy(runtime, serverName, mapOrOptions, maybeOptions) {
+    let mapPropertyToTool = defaultToolNameMapper;
+    let options;
+    if (typeof mapOrOptions === 'function') {
+        mapPropertyToTool = mapOrOptions;
+        options = maybeOptions;
+    }
+    else if (mapOrOptions) {
+        options = mapOrOptions;
+        if (typeof mapOrOptions.mapPropertyToTool === 'function') {
+            mapPropertyToTool = mapOrOptions.mapPropertyToTool;
+        }
+    }
+    const cacheSchemas = options?.cacheSchemas ?? true;
+    const initialSchemas = options?.initialSchemas ?? undefined;
+    const toolSchemaCache = new Map();
+    const persistedSchemas = new Map();
+    const toolAliasMap = new Map();
+    let schemaFetch = null;
+    let diskLoad = null;
+    let persistPromise = null;
+    let refreshPending = false;
+    let definitionForCache;
+    if (cacheSchemas) {
+        try {
+            definitionForCache = runtime.getDefinition(serverName);
+        }
+        catch {
+            definitionForCache = undefined;
+        }
+    }
+    if (cacheSchemas && !initialSchemas && definitionForCache) {
+        diskLoad = loadSchemasFromDisk(definitionForCache);
+        refreshPending = true;
+    }
+    if (initialSchemas) {
+        for (const [key, schemaRaw] of Object.entries(initialSchemas)) {
+            storeSchema(key, schemaRaw);
+        }
+        persistPromise = persistSchemas();
+    }
+    // consumePersist waits for any in-flight disk persistence to finish before reading from cache maps.
+    async function consumePersist() {
+        if (!persistPromise) {
+            return;
+        }
+        try {
+            await persistPromise;
+        }
+        finally {
+            persistPromise = null;
+        }
+    }
+    // ensureMetadata loads schema information for the requested tool, optionally refreshing from the server.
+    async function ensureMetadata(toolName) {
+        await consumePersist();
+        const cached = toolSchemaCache.get(toolName);
+        if (cached && !refreshPending) {
+            return cached;
+        }
+        if (diskLoad) {
+            try {
+                await diskLoad;
+            }
+            finally {
+                diskLoad = null;
+            }
+            if (toolSchemaCache.has(toolName) && !refreshPending) {
+                return toolSchemaCache.get(toolName);
+            }
+        }
+        if (!schemaFetch) {
+            schemaFetch = runtime
+                .listTools(serverName, { includeSchema: true })
+                .then((tools) => {
+                for (const tool of tools) {
+                    if (!tool.inputSchema || typeof tool.inputSchema !== 'object') {
+                        continue;
+                    }
+                    storeSchema(tool.name, tool.inputSchema);
+                }
+                persistPromise = persistSchemas();
+                refreshPending = false;
+            })
+                .catch((error) => {
+                schemaFetch = null;
+                throw error;
+            });
+        }
+        await schemaFetch;
+        await consumePersist();
+        return toolSchemaCache.get(toolName);
+    }
+    // storeSchema caches schema info locally and records aliases for lookup.
+    function storeSchema(key, schemaRaw) {
+        const info = createToolSchemaInfo(schemaRaw);
+        if (!info) {
+            return;
+        }
+        const canonical = mapPropertyToTool(key);
+        toolSchemaCache.set(canonical, info);
+        if (canonical !== key) {
+            toolSchemaCache.set(key, info);
+        }
+        const canonicalAlias = canonicalizeToolName(key);
+        if (!toolAliasMap.has(canonicalAlias)) {
+            toolAliasMap.set(canonicalAlias, key);
+        }
+        const mapperAlias = canonicalizeToolName(canonical);
+        if (!toolAliasMap.has(mapperAlias)) {
+            toolAliasMap.set(mapperAlias, key);
+        }
+        if (cacheSchemas && definitionForCache && isPlainObject(schemaRaw)) {
+            persistedSchemas.set(canonical, schemaRaw);
+        }
+    }
+    // loadSchemasFromDisk hydrates the in-memory cache from the persisted schema snapshot.
+    async function loadSchemasFromDisk(definition) {
+        try {
+            const snapshot = await readSchemaCache(definition);
+            if (!snapshot) {
+                return;
+            }
+            for (const [key, schemaRaw] of Object.entries(snapshot.tools)) {
+                storeSchema(key, schemaRaw);
+            }
+        }
+        catch {
+            // ignore cache read failures
+        }
+    }
+    // persistSchemas writes cached schema data to disk when enabled.
+    function persistSchemas() {
+        if (!cacheSchemas || !definitionForCache || persistedSchemas.size === 0) {
+            return null;
+        }
+        const definition = definitionForCache;
+        const snapshot = {
+            updatedAt: new Date().toISOString(),
+            tools: Object.fromEntries(persistedSchemas.entries()),
+        };
+        return writeSchemaCache(definition, snapshot).catch(() => {
+            // best-effort persistence
+        });
+    }
+    const base = {
+        call: async (toolName, options) => {
+            const result = await runtime.callTool(serverName, toolName, options ?? {});
+            return createCallResult(result);
+        },
+        listTools: (options) => runtime.listTools(serverName, options),
+    };
+    return new Proxy(base, {
+        get(target, property, receiver) {
+            if (Reflect.has(target, property)) {
+                return Reflect.get(target, property, receiver);
+            }
+            const propertyKey = property;
+            const canonicalKey = typeof propertyKey === 'string' ? canonicalizeToolName(propertyKey) : null;
+            let resolvedToolName = typeof propertyKey === 'string' && canonicalKey
+                ? (toolAliasMap.get(canonicalKey) ?? mapPropertyToTool(propertyKey))
+                : mapPropertyToTool(propertyKey);
+            return async (...callArgs) => {
+                let schemaInfo;
+                try {
+                    schemaInfo = await ensureMetadata(resolvedToolName);
+                }
+                catch {
+                    schemaInfo = undefined;
+                }
+                if (typeof propertyKey === 'string' && canonicalKey) {
+                    const alias = toolAliasMap.get(canonicalKey);
+                    if (alias && alias !== resolvedToolName) {
+                        resolvedToolName = alias;
+                        try {
+                            schemaInfo = await ensureMetadata(resolvedToolName);
+                        }
+                        catch {
+                            // ignore and keep prior schema if available
+                        }
+                    }
+                }
+                const positional = [];
+                const argsAccumulator = {};
+                const optionsAccumulator = {};
+                for (const arg of callArgs) {
+                    if (isPlainObject(arg)) {
+                        const keys = Object.keys(arg);
+                        const treatAsArgs = schemaInfo !== undefined &&
+                            keys.length > 0 &&
+                            (keys.every((key) => schemaInfo.propertySet.has(key)) ||
+                                keys.every((key) => !KNOWN_OPTION_KEYS.has(key)));
+                        if (treatAsArgs) {
+                            Object.assign(argsAccumulator, arg);
+                        }
+                        else {
+                            Object.assign(optionsAccumulator, arg);
+                        }
+                    }
+                    else {
+                        positional.push(arg);
+                    }
+                }
+                const explicitArgs = optionsAccumulator.args;
+                if (explicitArgs !== undefined) {
+                    delete optionsAccumulator.args;
+                }
+                const finalOptions = { ...optionsAccumulator };
+                let combinedArgs = explicitArgs;
+                if (schemaInfo) {
+                    const schema = schemaInfo;
+                    if (positional.length > schema.orderedKeys.length) {
+                        throw new Error(`Too many positional arguments for tool "${resolvedToolName}"`);
+                    }
+                    if (positional.length > 0) {
+                        const baseArgs = isPlainObject(combinedArgs) ? { ...combinedArgs } : {};
+                        positional.forEach((value, idx) => {
+                            const key = schema.orderedKeys[idx];
+                            if (key) {
+                                baseArgs[key] = value;
+                            }
+                        });
+                        combinedArgs = baseArgs;
+                    }
+                    if (Object.keys(argsAccumulator).length > 0) {
+                        const baseArgs = isPlainObject(combinedArgs) ? { ...combinedArgs } : {};
+                        Object.assign(baseArgs, argsAccumulator);
+                        combinedArgs = baseArgs;
+                    }
+                    if (combinedArgs !== undefined) {
+                        combinedArgs = applyDefaults(schema, combinedArgs);
+                    }
+                    else {
+                        const defaults = applyDefaults(schema, undefined);
+                        if (defaults && typeof defaults === 'object') {
+                            combinedArgs = defaults;
+                        }
+                    }
+                    validateRequired(schema, combinedArgs);
+                }
+                else {
+                    if (positional.length > 0) {
+                        combinedArgs = positional;
+                    }
+                    if (Object.keys(argsAccumulator).length > 0) {
+                        const baseArgs = isPlainObject(combinedArgs) ? { ...combinedArgs } : {};
+                        Object.assign(baseArgs, argsAccumulator);
+                        combinedArgs = baseArgs;
+                    }
+                }
+                if (combinedArgs !== undefined) {
+                    finalOptions.args = combinedArgs;
+                }
+                const result = await runtime.callTool(serverName, resolvedToolName, finalOptions);
+                return createCallResult(result);
+            };
+        },
+    });
+}
+//# sourceMappingURL=server-proxy.js.map

package/dist/server-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-proxy.js","sourceRoot":"","sources":["../src/server-proxy.ts"],"names":[],"mappings":"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"}

package/docs/RELEASE.md

@@ -0,0 +1,96 @@
+---
+summary: 'Release checklist for mcporter: versioning, tests, build artifacts, npm publish, GitHub release assets, and Homebrew tap updates.'
+read_when:
+  - 'Cutting a release or updating release automation'
+---
+
+# Release Checklist
+
+> **Runner note:** From the repo root run `export MCP_RUNNER="$PWD/runner"` and use `$MCP_RUNNER <command>` for every shell command listed below unless the step explicitly says otherwise. This keeps the guardrails active even when the checklist jumps between directories.
+
+> **Helper script:** You can run `./scripts/release.sh <phase>` (gates | artifacts | publish | smoke | tag | all) to execute the steps below with the runner by default. It stops on first error; rerun the next phase after fixing issues.
+
+> **No-warning policy:** Every command below must finish without warnings (Biome, Oxlint, tsgo, Vitest, npm pack, etc.). Fix issues before continuing; releases cannot ship with outstanding warnings.
+
+## Definition of “released”
+
+Shipping a release means **all** of:
+- Tag pushed (`v<version>`).
+- npm published (`mcporter@<version>` visible via `npm view mcporter version`).
+- GitHub release published for the tag **with assets + checksums**.
+- Homebrew tap updated (and verified) after assets propagate.
+
+1. Update version in package.json and src/runtime.ts.
+2. Run pnpm install to refresh the lockfile if dependencies changed.
+3. pnpm check (zero warnings allowed; abort immediately on any error)
+4. pnpm test (must finish with **0 failed**; if Vitest prints any red FAIL lines or a non-zero exit code, stop and fix it before proceeding)
+5. pnpm build
+6. pnpm build:bun
+7. tar -C dist-bun -czf dist-bun/mcporter-macos-arm64-v<version>.tar.gz mcporter
+8. shasum -a 256 dist-bun/mcporter-macos-arm64-v<version>.tar.gz | tee dist-bun/mcporter-macos-arm64-v<version>.tar.gz.sha256
+9. npm pack --pack-destination /tmp && mv /tmp/mcporter-<version>.tgz .  # keep the real tarball
+10. shasum mcporter-<version>.tgz > mcporter-<version>.tgz.sha1 && shasum -a 256 mcporter-<version>.tgz > mcporter-<version>.tgz.sha256
+11. Verify git status is clean.
+11. git commit && git push.
+12. pnpm publish --tag latest *(the runner already has npm credentials configured, so you can run this directly in the release shell; bump `timeout_ms` if needed because prepublish re-runs check/test/build and can take several minutes.)*
+13. `npm view mcporter version` (and `npm view mcporter time`) to ensure the registry reflects the new release before proceeding. If the new version isn’t visible yet, wait a minute and retry—npm’s replication can lag briefly.
+14. Sanity-check the “one weird trick” workflow from a **completely empty** directory (no package.json/node_modules) via:
+    ```bash
+    rm -rf /tmp/mcporter-empty && mkdir -p /tmp/mcporter-empty
+    cd /tmp/mcporter-empty
+    # run this without the runner because we are outside the repo and npx handles its own logging
+    npx mcporter@<version> generate-cli "npx -y chrome-devtools-mcp" --compile
+    ./chrome-devtools-mcp --help | head -n 5
+    ```
+    Only continue once the CLI compiles and the help banner prints.
+15. Draft the GitHub release notes using this template (copy/paste and edit). **Title the release `mcporter v<version>` (project name + version) to keep GitHub’s releases list consistent.**
+    ```markdown
+    ## Highlights
+    - <top feature>
+    - <second feature>
+    - <bugfix or UX callout>
+
+    SHA256 (mcporter-macos-arm64-v<version>.tar.gz): `<sha from step 8>`
+    SHA256 (mcporter-<version>.tgz): `<sha from npm pack>`
+    ```
+    Then **create the GitHub release for tag v<version>** and upload all assets:
+    - `mcporter-macos-arm64-v<version>.tar.gz`
+    - `mcporter-macos-arm64-v<version>.tar.gz.sha256` (from step 8; add a `.sha256` file)
+    - `mcporter-<version>.tgz` (from `npm pack`)
+    - `mcporter-<version>.tgz.sha1` and `mcporter-<version>.tgz.sha256`
+    Double-check the uploaded checksums match your local files.
+16. Tag the release (git tag v<version> && git push --tags).
+17. Post-tag housekeeping: add a fresh "Unreleased" stub to CHANGELOG.md (set to "- Nothing yet.") and start a new version section for the just-released patch if it isn’t already recorded.
+
+After the release is live, always update the Homebrew tap and re-verify both installers. That flow should be:
+
+1. Uninstall any existing `mcporter` binaries to avoid PATH conflicts:
+   ```bash
+   brew uninstall mcporter || true
+   npm uninstall -g mcporter || true
+   ```
+2. Install from Homebrew, run `brew test` equivalents (`mcporter list --help`), then uninstall so the npm install owns the global `mcporter` binary. If the install fails with a linking conflict (`bin/mcporter already exists`), run `brew link --overwrite mcporter` and rerun the smoke command before uninstalling:
+   ```bash
+   brew install steipete/tap/mcporter
+   # If you still have /opt/homebrew/bin/mcporter from npm, fix conflicts with:
+   # brew link --overwrite mcporter
+   mcporter list --help | head -n 5
+   brew uninstall mcporter
+   ```
+3. Install the npm package globally (or leave it to npx) and keep that version in place for day-to-day use:
+   ```bash
+   npm install -g mcporter@<version>
+   mcporter --version
+   ```
+4. Finally, run a fresh `npx mcporter@<version>` smoke test from an empty temp directory (no runner needed) to ensure the package is usable without global installs.
+
+17. Update `steipete/homebrew-tap` → `Formula/mcporter.rb` with the new version, tarball URL, and SHA256. Refresh the tap README highlights and changelog snippets so Homebrew users see the new version callouts. (That repo doesn’t include `runner`, so use regular git commands there.)
+18. Commit and push the tap update.
+19. Verify the Homebrew flow (after GitHub release assets propagate):
+    ```bash
+    brew update
+    brew install steipete/tap/mcporter
+    # If you previously installed mcporter via npm (or another tap) and see a link error,
+    # run `brew link --overwrite mcporter` to replace /opt/homebrew/bin/mcporter with the tap binary.
+    mcporter list --help
+    ```

package/docs/adhoc.md

@@ -0,0 +1,76 @@
+---
+summary: 'How to use mcporter’s ad-hoc HTTP/stdio flags to try MCP servers without editing config files.'
+read_when:
+  - 'Exploring or debugging unknown MCP endpoints'
+---
+
+# Ad-hoc MCP Servers
+
+mcporter is gaining support for "just try it" workflows where you point the CLI at a raw MCP endpoint without first editing a config file. This doc tracks the behavior and heuristics we use to make that experience smooth while keeping the runtime predictable.
+
+## Entry Points
+
+Two new flag sets let you describe a server on the command line:
+
+- `mcporter list --http-url https://mcp.linear.app/mcp [--name linear]`
+- `mcporter call --stdio "bun run ./server.ts" --name local-tools`
+
+You can also pass a bare URL as the selector (`mcporter list https://mcp.linear.app/mcp`) or embed the URL in a `call` expression (`mcporter call 'https://mcp.example.com/tools.generate({ topic: "release" })'`).
+- Add `--json` to `mcporter list …` when you need a machine-readable summary of status counts and per-server failures, use `--output json`/`--output raw` with `mcporter call` to receive structured `{ server, tool, issue }` envelopes whenever a transport error occurs, and run `mcporter auth … --json` to capture the same envelope if OAuth or transport setup fails.
+
+### Example: HTTP ad-hoc workflow
+
+```bash
+# Inspect the server directly via URL (no config entry needed)
+mcporter list 'https://mcp.sentry.dev/mcp?agent=1'
+
+# Call a tool by repeating the same URL + tool suffix
+mcporter call 'https://mcp.sentry.dev/mcp?agent=1.use_sentry(request: "yo whats up")'
+```
+
+Notice that the second command repeats the URL. Ad-hoc definitions are ephemeral unless you pass `--persist`, so there is no stored server named `mcp-sentry-dev-mcp` yet. Reusing the printed slug only works after you persist the definition (see "Naming & Identity" below) or add the server to your config; otherwise keep passing the URL/stdio selector each time.
+
+## Transport Detection
+
+- **HTTP(S)**: Providing a URL defaults to the streamable HTTP transport. `https://` works out of the box; `http://` requires `--allow-http` (or the hidden alias `--insecure`) to acknowledge cleartext traffic. The `--sse` flag is a hidden alias for `--http-url` to match older examples.
+- **STDIO**: Supplying `--stdio` (with a command string) or `--stdio-bin` (binary + args) selects the stdio transport. Your current shell environment is inherited automatically; use `--env KEY=value` only when you need to inject/override specific variables (and `--cwd` to change directories).
+- **Conflict guard**: Passing both URL and stdio flags errors out so we don’t guess.
+
+## Naming & Identity
+
+- `--name` wins when provided.
+- Otherwise we derive a slug:
+  - HTTP: `<host>` plus a sanitized path fragment (e.g. `mcp-linear-app-mcp`).
+  - STDIO: executable basename + script (`node-singlestep`).
+- Until you persist the definition (via `--persist`, `mcporter config add`, etc.), the slug is **only** used as the cache key for OAuth tokens/log prefs—you still need to supply the ad-hoc descriptor (`--http-url`, `--stdio`, or bare URL) every time you invoke `mcporter list|call|auth`.
+- Once persisted, the slug becomes a normal server name so `mcporter call <slug>.tool` and `mcporter auth <slug>` work just like any other configured entry.
+- If you don’t persist the definition, run `mcporter auth https://mcp.linear.app/mcp` (or supply `--name linear` so `mcporter auth linear` also works) to finish OAuth with the same settings.
+
+This name becomes the cache key for OAuth tokens and log preferences, so repeated ad-hoc calls still benefit from credential reuse.
+
+## OAuth Auto-Detection
+
+Many hosted MCP servers (Supabase, Vercel, etc.) advertise OAuth capabilities but expect clients to discover this dynamically. When an ad-hoc HTTP server responds with `401/403` during the initial handshake, mcporter now:
+
+1. **Promotes the definition to OAuth** and spins up the default browser flow—no need to edit config or supply `auth: "oauth"` manually.
+2. **Persists the change** whenever you pass `--persist`, so future runs remember that the endpoint requires OAuth without repeating the detection step.
+
+The CLI still avoids surprise prompts during `mcporter list`; the upgrade happens the first time you run `mcporter auth <url>` or any other command that allows OAuth (i.e., not in `--autoAuthorize=false` mode).
+
+## Auth & Persistence
+
+- OAuth flows are allowed; successful tokens store under the inferred name just like regular definitions.
+- `mcporter auth` accepts the same `--http-url/--stdio` flags (and even bare URLs), so you can immediately re-run `mcporter auth https://…` after a 401 without touching a config file.
+- For remote environments, run `mcporter auth <url> --browser none`, open the printed URL locally, then complete the flow with `mcporter auth complete '<failed-localhost-redirect>'`.
+- Nothing is written to disk unless you pass `--persist /path/to/config.json`. When set, we merge the generated definition into that file (creating it if necessary) so future runs can rely on the standard config pipeline.
+
+## Safety Nets
+
+- Non-HTTPS endpoints require `--allow-http`.
+- For stdio commands we print a confirmation snippet the first time we see a new command unless `--yes` is present.
+- Missing transports or malformed combinations throw descriptive errors, pointing to `docs/adhoc.md` for guidance.
+
+## Follow-ups
+
+- Extend `mcporter config add` to leverage the same helper, making it the one-stop path from exploration to permanence.
+- Consider caching inference results so repeated URL calls automatically rehydrate the previous settings (env/cwd).

package/docs/call-heuristic.md

@@ -0,0 +1,31 @@
+---
+summary: 'Explains mcporter call’s typo heuristics, auto-correction thresholds, and suggestion behavior.'
+read_when:
+  - 'Tool invocations fail due to misspelled names'
+---
+
+# Call Command Auto-Correction
+
+`mcporter call` aims to help when a tool name is *almost* correct without hiding real mistakes.
+
+## Confident Matches → Auto-Correct
+- We normalise tool names (strip punctuation, lowercase) and compute a Levenshtein distance.
+- If the distance is ≤ `max(2, floor(length × 0.3))`, or the names only differ by case/punctuation, we retry automatically.
+- A dim informational line explains the correction: `[mcporter] Auto-corrected tool call to linear.list_issues (input: linear.listIssues).`
+
+## Low-Confidence Matches → Suggest
+- When the best candidate falls outside the threshold we keep the original failure.
+- We still print a hint so the user learns the canonical name: `[mcporter] Did you mean linear.list_issue_statuses?`
+- No second call is attempted in this case.
+
+## Edge Cases
+- We only inspect the tool catalog if the server explicitly replied with “Tool … not found”. Other MCP errors surface untouched.
+- If listing tools itself fails (auth, offline, etc.) we skip both auto-correct and hints.
+- Behaviour is covered by `tests/cli-call.test.ts`.
+
+## Server Selection Heuristic
+
+- `mcporter list <server>` now applies the same edit-distance heuristic to server names. If you type `vercek`, the CLI auto-corrects to `vercel` (and logs `[mcporter] Auto-corrected server name to vercel (input: vercek).`).
+- When the typo is too large, we keep the original failure but emit a hint: `[mcporter] Did you mean linear?` followed by the usual “Unknown MCP server …” line. This avoids giant stack traces while pointing to the right name.
+- The heuristic considers every configured server (including ad-hoc ones registered via `--http-url/--stdio`). Tests covering this behaviour live in `tests/cli-list.test.ts`.
+- `mcporter auth` shares the same routing logic, so `mcporter auth https://mcp.example.com/mcp` (or even `mcporter auth vercek`) will spin up the temporary definition, auto-correct close names, and launch OAuth without touching the config file.

package/docs/call-syntax.md

@@ -0,0 +1,75 @@
+---
+summary: 'Reference for mcporter call argument styles, CLI signatures, and structured output modes.'
+read_when:
+  - 'Working on call CLI UX or documenting invocation examples'
+---
+
+# Call Syntax Reference
+
+`mcporter call` now understands two complementary styles:
+
+| Style | Example | Notes |
+|-------|---------|-------|
+| Flag-based (compatible) | `mcporter call linear.create_comment --issue-id LNR-123 --body "Hi"` | Use `key=value`, `key:value`, or `key: value` pairs—ideal for shell scripts. |
+| Function-call (expressive) | `mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hi")'` | Mirrors the pseudo-TypeScript signature shown by `mcporter list`; unlabeled values map to schema order. |
+| Structured output | `mcporter call 'linear.create_comment(...)' --output json` | Successful calls emit JSON bodies; failures emit `{ server, tool, issue }` envelopes so automation can react to auth/offline/http errors. |
+
+Both forms share the same validation pipeline, so required parameters, enums, and formats behave identically.
+
+## Reading the CLI Signatures
+
+`mcporter list <server>` prints each tool as a compact TypeScript declaration:
+
+```ts
+/**
+ * Create a comment on a specific Linear issue.
+ * @param issueId The issue ID
+ * @param body The content of the comment as Markdown
+ * @param parentId? A parent comment ID to reply to
+ */
+function create_comment(issueId: string, body: string, parentId?: string): Comment;
+// optional (3): notifySubscribers, labelIds, mentionIds, ...
+```
+
+Key details:
+
+- Doc blocks use `@param` lines so every parameter description (even optional ones) stays in view.
+- Required parameters appear without `?`; optional parameters use `?` and inherit enum literals (e.g. `"json" | "markdown"`).
+- Known format hints are appended inline: `dueDate?: string /* ISO 8601 */` (we suppress the hint when the description already calls it out).
+- When a tool exposes more than two optional parameters (or has ≥4 required parameters), the default output hides the extras and replaces them with an inline summary like `// optional (8): limit, before, after, orderBy, projectId, ...`.
+- Run `mcporter list <server> --all-parameters` whenever you want the full signature; the footer repeats `Optional parameters hidden; run with --all-parameters to view all fields.` any time truncation occurs.
+- Return types come from each tool’s output schema, so you’ll see concrete names when providers include `title` metadata (e.g. `DocumentConnection`). When no schema is advertised we omit the `: Type` suffix entirely instead of showing `unknown`.
+- Each server concludes with a short `Examples:` block that mirrors the preferred function-call syntax.
+
+## Function-Call Syntax Details
+
+- **Named arguments preferred**: `issueId: "123"` keeps calls self-documenting. When labels are omitted, mcporter falls back to positional order defined by the tool schema.
+- **Optional positional fallback**: omit labels when calling `mcporter 'context7.resolve-library-id("react")'`—arguments map to the schema order after any explicitly named parameters.
+- **Literals supported**: strings, numbers, booleans, `null`, arrays, and nested objects. For strings containing spaces or commas, wrap the entire call in single quotes to keep the shell happy.
+- **Error feedback**: invalid keys, unsupported expressions, or parser failures bubble up with actionable messages (`Unsupported argument expression: Identifier`, `Unable to parse call expression: …`).
+- **Server selection**: You can embed the server in the expression (`linear.create_comment(...)`) or pass it separately (`--server linear create_comment(...)`).
+
+## HTTP Selectors & Ad-hoc URLs
+
+- You can skip `--server` entirely by pasting the MCP endpoint + tool name directly: `mcporter call 'https://www.shadcn.io/api/mcp.getComponent(component: "vortex")'`.
+- Mcporter strips the `.tool` suffix to derive the base server URL, reuses any configured definition that already points at that endpoint, and only registers a new ad-hoc server when necessary (`--allow-http` still guards plain HTTP URLs).
+- Function-call arguments continue to work in this form; if you omit parentheses you can still append `key=value` pairs (`https://.../mcp.getComponent component=vortex`).
+- This is especially handy for copy/pasting tool listings or experimenting with anonymous HTTP MCP servers—you get the same parsing, auto-correction, and logging pipeline as the regular `server.tool` syntax.
+- Protocols are optional; bare domains such as `shadcn.io/api/mcp.getComponents` automatically assume `https://`. If you really need plain HTTP, spell out `http://` and pass `--allow-http`.
+- Hostname comparisons ignore a leading `www.` so `https://shadcn.io/api/mcp` and `https://www.shadcn.io/api/mcp` resolve to the same configured server when possible.
+
+## Tips
+
+- Use `--args '{ "issueId": "LNR-123" }'` if you already have JSON payloads—nothing changed for that workflow.
+- The new syntax respects all existing features (timeouts, `--output`, auto-correction).
+- Required fields show by default; pass `--all-parameters` when you want the full parameter list (or `--schema` for raw JSON schemas).
+- When in doubt, run `mcporter list <server>` to see the current signature and sample invocation.
+
+## Flag-Based Syntax Details
+
+- `key=value`, `key:value`, and `key: value` all map to the same named-argument handling, so you can type whichever feels most natural for your shell.
+- By default, arguments keep the same validation pipeline as the function-call syntax—enums, numbers, and booleans are coerced automatically, and missing required fields raise errors.
+- `--raw-strings` disables numeric coercion for flag-style and positional values so IDs/codes stay literal strings (`code=12345` stays `"12345"`).
+- `--no-coerce` disables all coercion for flag-style and positional values (`true`, `null`, and JSON-like values remain strings).
+- `--save-images <dir>` keeps stdout formatting untouched while writing image content blocks to disk when a tool response includes `type: "image"` entries.
+- `tool=value`/`tool:value` and `server=value` still act as aliases for `--tool` / `--server` when you need to override the selector.