ip-search-mcp 0.0.0-stage → 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# Architecture
+
+## Shape
+
+```
+MCP client
+   |
+   v
+src/server.ts  (tool registration, zod input schemas, output formatting)
+   |
+   +-- domain/            pure logic, no network
+   |     assessment      concept screen (101 risks, CPC/Nice, closest hits)
+   |     claims          claim parsing, dependency graph, 112 lint
+   |     disclosure      102(b)(1) clock arithmetic
+   |     drawings/       rules (1.84), geometry (SVG parse), render, validate
+   |     spec            specification assembly, claim scaffold, packet
+   |
+   +-- providers/         one module per data source
+   |     odp   tsdr   ops   ppubs (opt-in)   tmsearch (opt-in)   index (sqlite)
+   |
+   +-- http.ts            fetch, retry, rate limit, cache, credential host check
+   +-- numbers.ts         patent and trademark identifier normalization
+   +-- config.ts          env parsing, provider flags, credential state
+```
+
+Domain modules never import providers. Providers never format user-facing text. The server composes them.
+
+`ip-axi` sits beside the server as a presentation layer. It creates the same server in process, connects over an in-memory MCP transport, and calls tools through the MCP client, so command behavior cannot drift from tool behavior. Only formatting, flag parsing, and exit codes live in `src/axi/`.
+
+## Provider boundaries
+
+| Provider | Host | Auth | Stability |
+|----------|------|------|-----------|
+| ODP | `api.uspto.gov` | `X-API-KEY` | Documented API, docs and swagger behind a USPTO.gov login |
+| TSDR | `tsdrapi.uspto.gov` | `USPTO-API-KEY` | Documented, identifier lookup only |
+| EPO OPS | `ops.epo.org` | OAuth2 client credentials | Documented, fair-use quota |
+| PPUBS | `ppubs.uspto.gov` | session token | Undocumented, opt-in |
+| tmsearch | `tmsearch.uspto.gov` | WAF cookie (optional) | Undocumented, opt-in, backend base discovered at runtime |
+| index | local file | none | Derived from ODP bulk XML |
+
+Each provider normalizes into `PatentHit`, `TrademarkHit`, `PatentDocument`, or a raw record, and every hit carries `Provenance`: provider, route, retrieval time, source id, and an `undocumented` flag when it applies.
+
+## Credential isolation
+
+`http.ts` refuses to send a request whose host is not the provider's configured host. Keys are attached inside the provider module, never passed in by a tool argument, never logged, and redacted in error details. ODP and TSDR use separate keys; the server never substitutes one for the other.
+
+## Rate limits
+
+| Bucket | Limit | Basis |
+|--------|-------|-------|
+| `tsdr:default` | 60/min | USPTO published limit |
+| TSDR PDF/ZIP | 4/min | Not wired: this server links to bundles rather than downloading them |
+| `odp:default` | 60/min | Conservative; ODP publishes limits on its own page |
+| `ops:default` | 60/min | EPO fair-use charter |
+| `ppubs:default` | 30/min | Undocumented; deliberately conservative |
+| `tmsearch:default` | 30/min | Undocumented; deliberately conservative |
+
+The limiter is a sliding window shared per bucket across the process. Retries honor `Retry-After` and use exponential backoff for 429 and 5xx.
+
+## Caching
+
+File cache under `~/.cache/ip-search-mcp`, keyed by a SHA-256 of provider, URL, and body, with a per-call TTL (5 minutes for searches, 1 minute for case status, 30 minutes to 1 hour for metadata and bibliographic data). Writes are atomic (temp file then rename). Cache hits are marked `cached: true` in provenance.
+
+## Drawing pipeline
+
+1. `renderSheet` emits an SVG in millimetre coordinates: A4 or letter, fixed margins, no sight frame, scan targets in two catercorner corners, header indicia inside the top margin, sheet numbering, and reference characters at 4 mm.
+2. `geometry.ts` parses any SVG back into primitives with transforms applied: rect, line, circle, ellipse, polygon, polyline, path (M/L/H/V/C/Q/S/T/A/Z with curve sampling), and text with estimated bounds. Unsupported constructs are reported, not guessed.
+3. `validate.ts` checks the parsed primitives against the encoded rules and returns findings with rule ids and citations, plus a list of things geometry cannot verify (part identity across views, projection lines, print reduction, shading correctness).
+
+The rule set is data in `rules.ts`, sourced from eCFR title 37 section 1.84 on 2026-11-10. `drawing_rules` returns it with the source URL and retrieval date so a reader can check freshness.
+
+## Claims pipeline
+
+`parseClaims` splits numbered claims, extracts dependency phrases (including ranges and "or"/"and"), and builds a dependency graph. Lint covers sequential numbering, forward references, multiple dependent claims built on multiple dependent claims, alternative form, antecedent basis using transitive ancestors, means-plus-function triggers, relative terms, specification support, abstract length, and title limits. Antecedent basis uses a head-final noun heuristic; it is a screening aid, not a parser.
+
+## Drafting
+
+`draftSpecification` assembles sections in the order examiners expect and reports every section the caller did not supply as a gap. It never invents content. `draftClaims` builds an independent claim from supplied elements and never adds limitations. Every artifact starts with `DRAFT - NOT FOR FILING`.
+
+There is no submission code path anywhere in the server: no EFS-Web, Patent Center, TEAS, or EPO Online Filing client, no signature handling, and no credentials for any filing system.
+
+## Local index
+
+`node:sqlite` with FTS5 over `patents` and `trademarks` tables. Ingest walks a directory of XML, detects patent grant, published application, and trademark record shapes, extracts text subtrees (abstract, claims, description, goods and services), and writes both the row and its FTS entry. Search returns `bm25` order with the `index` provider label.
+
+One file can hold thousands of records: `<case-file>` blocks are split and parsed individually so a daily TDXF file indexes every application and memory stays bounded. Patent grant and application XML files are parsed whole. Limits: ingest is not incremental across releases beyond `INSERT OR REPLACE`; field mapping follows the documented TDXF and ICE names and must be checked against the data dictionary for a given snapshot. Measured: 7,330 trademark records from a 143 MB file in 60 seconds.
+
+## Failure behavior
+
+Errors are typed (`CREDENTIAL_MISSING`, `PROVIDER_DISABLED`, `RATE_LIMITED`, `UPSTREAM`, `NOT_FOUND`, `INVALID_INPUT`, `UNSUPPORTED_FORMAT`). Tools return them as `isError` results with an actionable hint. Nothing crashes the process, and no error is converted into an empty success.

package/CREDENTIALS.md

@@ -0,0 +1,107 @@
+# Credentials
+
+This server never asks a tool caller for a key. Keys come from the process environment, and each key is bound to one host.
+
+## Where to put a key
+
+Pick one location per use.
+
+**Agents and MCP clients.** Fill the `env` block of the `ip-search-mcp` entry in `~/.agents/mcp.json`, then restart the harness so the server is respawned:
+
+```json
+"ip-search-mcp": {
+  "command": "node",
+  "args": ["C:/Users/brand/Desktop/ip-search-mcp/dist/src/index.js"],
+  "env": {
+    "USPTO_ODP_API_KEY": "your-odp-key",
+    "USPTO_TSDR_API_KEY": "your-tsdr-key"
+  }
+}
+```
+
+Empty strings are treated as unset, so leaving a slot blank is safe.
+
+**Your shell, for CLI runs and tests.** Set the variables for the session, or persist them to the user profile:
+
+```powershell
+$env:USPTO_ODP_API_KEY = "your-odp-key"
+$env:USPTO_TSDR_API_KEY = "your-tsdr-key"
+[Environment]::SetEnvironmentVariable("USPTO_ODP_API_KEY", "your-odp-key", "User")
+```
+
+**A local `.env` file.** The server does not load `.env` by itself. Pass it explicitly:
+
+```bash
+node --env-file=.env dist/src/index.js
+```
+
+`.env` is gitignored. Never put a key in a tool argument, a prompt, a commit, or a skill file.
+
+**Verify.** This prints booleans only, never key values:
+
+```bash
+node dist/src/index.js status
+```
+
+A provider shows `configured: true` only when its full set of variables is non-empty.
+
+## USPTO Open Data Portal (ODP)
+
+Used for: patent file wrapper search, metadata, continuity, documents, bulk products.
+
+1. Create a USPTO.gov account and enable multi-factor authentication.
+2. Sign in at https://data.uspto.gov.
+3. Open Manage API Key and create a key.
+4. Keep the four profile fields the portal requires current; keys for incomplete profiles can be deactivated.
+5. Set `USPTO_ODP_API_KEY`.
+
+Sent only to `api.uspto.gov` as `X-API-KEY`. ODP documentation and swagger sit behind the same sign-in.
+
+## TSDR (trademark status and documents)
+
+Used for: authoritative case status, documents, mark images.
+
+1. Create or sign in to a USPTO.gov account.
+2. Open https://account.uspto.gov/api-manager/ and create a TSDR key.
+3. Set `USPTO_TSDR_API_KEY`.
+
+Sent only to `tsdrapi.uspto.gov` as `USPTO-API-KEY`. This is a different credential from the ODP key. TSDR is an identifier lookup, not a search engine: you need a serial, registration, IR, or reference number.
+
+## EPO Open Patent Services (OPS)
+
+Used for: worldwide bibliographic data, full text, families, images.
+
+1. Register at https://developers.epo.org.
+2. Create an application to get a consumer key and secret.
+3. Set `EPO_OPS_CLIENT_ID` and `EPO_OPS_CLIENT_SECRET`.
+
+OAuth2 client-credentials token against `ops.epo.org`; the token is cached until shortly before expiry. Usage is governed by the EPO fair use charter.
+
+## Undocumented surfaces (off by default)
+
+| Variable | Effect |
+|----------|--------|
+| `IP_ALLOW_UNOFFICIAL=1` | Enables Patent Public Search and the Trademark Search backend adapters |
+| `TMSEARCH_WAF_TOKEN` | Optional `aws-waf-token` cookie copied from a browser session |
+
+Both surfaces have no published contract, can change shape without notice, and sit behind terms of use that permit the USPTO to cut off automated access. Results from them are labeled `undocumented: true` in provenance.
+
+## Operational settings
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `IP_CACHE_DIR` | `~/.cache/ip-search-mcp` | File cache |
+| `IP_INDEX_DB` | `~/.cache/ip-search-mcp/ip-index.sqlite` | Local FTS index |
+| `IP_TIMEOUT_MS` | `30000` | Per-request timeout |
+| `IP_MAX_RETRIES` | `2` | Retry count for 429, 5xx, and network errors |
+| `IP_USER_AGENT` | `ip-search-mcp/0.1.0 (stdio MCP server)` | User-Agent header |
+| `PPUBS_BASE_URL`, `TMSEARCH_BASE_URL`, `USPTO_ODP_BASE_URL`, `USPTO_TSDR_BASE_URL`, `EPO_OPS_BASE_URL` | provider defaults | Host overrides for testing only |
+
+Overriding a base URL does not let a key travel to the new host: the host check compares against the configured base, and keys are attached after that check.
+
+## Handling rules
+
+- Do not pass keys through tool arguments, prompts, or committed files.
+- Do not copy a key from one provider's console to another provider's variable.
+- Rotate a key if it appears in a transcript, log, or error message.
+- Error details redact `authorization`, `x-api-key`, `uspto-api-key`, and `x-access-token`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Phillips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LIMITS.md

@@ -0,0 +1,65 @@
+# Limits
+
+## What no implementation can fix
+
+- **No official USPTO trademark search API exists.** TSDR is identifier lookup only. The Trademark Search web app has no documented API; its backend is used by the UI and carries terms-of-use risk. Real discovery requires either that backend, a local index over the trademark daily XML, or a paid third party.
+- **PatentsView is gone.** The legacy API was retired in May 2025 and the Search API shut down in March 2026; its data moved to ODP bulk products. Any guide pointing at `api.patentsview.org` or `search.patentsview.org` is stale.
+- **ODP API documentation requires a USPTO.gov sign-in.** Endpoint paths in this server come from the published OpenAPI surface and a bound client; response shapes for fields not exercised here can differ and surface as raw payloads rather than normalized hits.
+- **EPO OPS is not a US legal record.** It is bibliographic and family data; verify status and documents against USPTO records.
+
+## Verified against live providers, 2026-11-10
+
+Observed with real USPTO keys, then encoded in the tests and provider code.
+
+- **ODP free-text search works.** A plain-language phrase returned 425,510 matching applications with title, filing date, inventor, assignee, status, and application number normalized correctly.
+- **ODP answers a zero-hit search with HTTP 404** and `"No matching records found"`. The provider converts that to an empty result set, not an error.
+- **ODP date-range filtering is not verified.** Four documented shapes (`rangeFilters` with ISO dates, compact dates, and both `filingDate` and `applicationFilingDate`; `filters` with range strings) all returned 404 or 400. `patents_search` therefore rejects `from`/`to` for the ODP provider and routes date-bounded queries to EPO OPS or the local index. ODP sort and filter field names are likewise unverified.
+- **ODP documents live under `documentBag[].downloadOptionBag[]`.** The provider flattens them to code, description, official date, page count, and PDF URL. A 2026 application returned 53 documents.
+- **TSDR returns namespaced ST.96 XML.** With namespace prefixes removed, `ApplicationNumberText`, `RegistrationNumber`, `MarkVerbalElementText`, `NationalStatusExternalDescriptionText`, `ApplicationDate`, `RegistrationDate`, `ClassNumber`, and `EntityName` map correctly. Serial 87454105 returned DOCKER, ACTIVE, registration 6096739, Docker, Inc., class 9, and 57 documents.
+- **Bulk ingest works at record scale.** A real trademark daily file (7.7 MB compressed, 143 MB XML, 7,330 case-file records) indexed in 60 seconds with zero skips and searchable rows. Each case-file is parsed separately, so daily files no longer collapse to one record.
+- **Not yet exercised live:** EPO OPS (no credentials), Patent Public Search, and the Trademark Search backend (both opt-in).
+
+## Search quality
+
+- Text search is not classification search. A keyword result set can miss an entire CPC class.
+- Term overlap between a concept and a reference orders references for human review; it does not show disclosure.
+- Ranking is textual. It is not a likelihood-of-confusion score for trademarks and not an obviousness judgment for patents.
+- A zero-result search is recorded as a zero-result search. It is never evidence of novelty.
+
+## Drawing validation
+
+Checked: sheet size, margins and sight, frames, ink color, stroke weight, minimum text height, reference-character form and line crossings, view overlap, figure labels, prohibited scale text, description coverage of reference characters, sheet numbering, hatch spacing.
+
+Not checked, because geometry cannot decide it:
+
+- Whether the same reference character designates the same part across views.
+- Whether views are connected by projection lines or contain center lines.
+- Whether the scale survives two-thirds reproduction.
+- Whether shading correctly communicates surface form.
+- Whether a photograph is the only practicable medium (1.84(b)).
+
+Formats: SVG only. PDF and PNG are not parsed; convert a sheet to SVG or validate the generated SVG. A PDF checklist is a practitioner task.
+
+## Drafting
+
+- `application_draft` assembles supplied content and reports gaps. It does not invent background, embodiments, or claim limitations.
+- `claims_draft` writes one independent claim from supplied elements. Dependent claims and scope decisions are human work.
+- Claim lint is heuristic. Antecedent basis uses head-final noun detection, specification support uses content-word overlap, and both can miss or over-flag. Findings are screening aids with citations, not rejections.
+- No ADS, declaration, assignment, or fee calculation is produced.
+
+## Disclosure clock
+
+`disclosure_review` does arithmetic on dates you supply. It does not know about the inventor's earlier priority filing, derivation proceedings, experimental use, or national exceptions beyond the flags it states. Confirm every date with counsel.
+
+## Undocumented provider risk
+
+`IP_ALLOW_UNOFFICIAL=1` enables adapters for:
+
+- `ppubs.uspto.gov` session and search endpoints.
+- `tmsearch.uspto.gov` configuration discovery and the Elasticsearch-style search backend.
+
+Both can break on any USPTO deploy. Both are subject to USPTO terms of use, which state that unusually high automated access may be denied and that website interfaces are not a bulk-data source. Use the local index or official APIs when reliability matters. When these adapters run, hits are labeled `undocumented: true` and are candidates only.
+
+## Legal
+
+Nothing here is legal advice, an opinion of patentability, a registrability opinion, a clearance search, or a freedom-to-operate analysis. Every artifact is a draft for a licensed practitioner. The server has no filing, signature, or submission capability by design.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# ip-search-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for patent and trademark research plus review-only drafting of patent application artifacts.
+
+It searches official and bulk-derived sources, keeps provenance on every hit, screens concepts for patentability and registrability signals, and produces drawings, claims, specifications, and an attorney packet. It never files, signs, or submits anything.
+
+## Status
+
+Working: ODP file wrapper, TSDR lookup, EPO OPS, local SQLite FTS index, 37 CFR 1.84 drawing generation and validation, claim parsing and linting, disclosure-clock arithmetic, concept assessment, attorney packet assembly.
+
+Opt-in only: Patent Public Search and the Trademark Search backend. Both are undocumented USPTO surfaces with no published contract; enable with `IP_ALLOW_UNOFFICIAL=1` only if you accept that risk.
+
+## Quickstart
+
+```bash
+pnpm install
+pnpm build
+node dist/src/index.js --help
+```
+
+Register it with an MCP client over stdio:
+
+```json
+{
+  "mcpServers": {
+    "ip-search-mcp": {
+      "command": "node",
+      "args": ["C:/Users/brand/Desktop/ip-search-mcp/dist/src/index.js"],
+      "env": {
+        "USPTO_ODP_API_KEY": "...",
+        "USPTO_TSDR_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+No keys are required to run; without them keyed tools return a `CREDENTIAL_MISSING` error with setup instructions, and unkeyed sources are what remain.
+
+Where keys go, and how to verify them without printing their values:
+
+```bash
+node dist/src/index.js status
+```
+
+See `CREDENTIALS.md` for the MCP `env` block, shell variables, and `--env-file`.
+
+## Tools
+
+| Tool | Reads | Writes | Notes |
+|------|-------|--------|-------|
+| `credential_status` | yes | no | Provider table and required env vars |
+| `concept_assessment` | yes | no | 101 screen, CPC/Nice guesses, closest hits, distinctiveness band |
+| `patents_search` | yes | no | ODP, OPS, local index, opt-in PPUBS |
+| `patent_get` | yes | no | File wrapper metadata, continuity, bibliographic data |
+| `patent_documents` | yes | no | ODP prosecution document list |
+| `patent_family` | yes | no | EPO OPS family |
+| `trademarks_search` | yes | no | Candidates only; hydrate with `trademark_get` |
+| `trademark_get` | yes | no | Authoritative TSDR status |
+| `trademark_documents` | yes | no | TSDR documents and bundle PDF |
+| `prior_art_report` | yes | no | Multi-query report with provenance and gaps |
+| `drawing_spec` | no | optional file | Compliant SVG sheet |
+| `drawing_validate` | yes | no | 37 CFR 1.84 findings with citations |
+| `drawing_rules` | yes | no | Encoded rules and eCFR source |
+| `application_draft` | no | optional file | Specification in examiner-expected order |
+| `claims_draft` | no | no | Independent claim from supplied elements |
+| `application_lint` | yes | no | Claim, abstract, and title checks |
+| `disclosure_review` | yes | no | 102(b)(1) grace clock |
+| `attorney_packet` | yes | optional file | Review packet |
+| `index_build` | yes | yes | Local FTS5 index over bulk XML |
+
+## Shell interface: `ip-axi`
+
+An AXI-compliant CLI over the same tools, for shell use and scripted work.
+
+```bash
+node dist/src/axi/index.js                                  # live provider and index status
+node dist/src/axi/index.js patents search "optical sensor" --limit 5
+node dist/src/axi/index.js patents docs 19131214 --code CTNF
+node dist/src/axi/index.js trademarks get 87454105
+node dist/src/axi/index.js drawings validate ip/drawings/fig-1.svg --description @ip/specification.md
+node dist/src/axi/index.js index build --from <dir-of-bulk-xml>
+```
+
+Run `npm link` once in the repo to put `ip-axi` on PATH; afterwards the bare command works from any directory. `pnpm exec ip-axi` also works inside the repo. `npx -y ip-axi` works only after the package is published.
+
+Behavior: TOON output, totals on every list, `--fields` for extra columns, `--full` to stop truncation, exit codes 0 success / 1 error / 2 usage, structured errors on stdout with a fixing command, and a `next[]` block after every result.
+
+`axi-axi validate` reports 11 pass, 0 fail, 1 warn on Windows. The warning is the validator's own limitation: it spawns `npm` without the `.cmd` suffix, so its skill freshness probe cannot start. `npm run skill:check` passes directly and is the real check.
+
+## Local index
+
+```bash
+node dist/src/index.js index build --from <dir-of-xml> --db ~/.cache/ip-search-mcp/ip-index.sqlite
+node dist/src/index.js index status
+```
+
+Bulk XML comes from the ODP bulk data directory (patent grants, published applications, trademark daily XML). The ingest is best-effort over the documented field names; verify field mapping against the USPTO data dictionary for the snapshot you use.
+
+Verified on a real ODP product, 2026-11-10: the trademark daily applications file `apc261107.zip` (7.7 MB compressed, 143 MB XML, 7,330 case-file records) indexed in 60 seconds with zero skips. Dates are normalized to ISO. Each `case-file` becomes one row, so a daily file is searched record by record instead of collapsing to its first entry.
+
+```bash
+node dist/src/axi/index.js index build --from ./apc261107 --db ./ip-index.sqlite
+```
+
+Trademark records from TDXF carry no status description text, only a status code, so `status` is empty for those rows until a status-code table is joined.
+
+## Documentation
+
+- `ARCHITECTURE.md`: data flow, provider boundaries, provenance, caching, rate limits.
+- `CREDENTIALS.md`: how to obtain each key and how keys are isolated.
+- `LIMITS.md`: what no tool can do, and which surfaces carry terms-of-use risk.
+
+## Legal
+
+Not legal advice. This server produces research and drafts for review by a licensed patent or trademark practitioner. No output is a filing, an opinion of patentability, a clearance opinion, or a freedom-to-operate analysis.
+
+Companion reactive skill: `ip-filing-prep` in `~/Desktop/skills/ip-filing-prep`.

package/dist/src/axi/args.js

@@ -0,0 +1,83 @@
+import { UsageError } from "./errors.js";
+export function validFlagsHint(spec) {
+    const names = spec.flags.map((flag) => `--${flag.name}`);
+    names.push("--help");
+    return `valid flags for '${spec.name || "ip-axi"}': ${names.join(", ")}`;
+}
+export function parseArgs(argv, spec) {
+    const flags = {};
+    for (const flag of spec.flags) {
+        if (flag.default !== undefined)
+            flags[flag.name] = flag.default;
+    }
+    const positionals = [];
+    let help = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--help" || token === "-h") {
+            help = true;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            let name = token.slice(2);
+            let inline;
+            const equals = name.indexOf("=");
+            if (equals >= 0) {
+                inline = name.slice(equals + 1);
+                name = name.slice(0, equals);
+            }
+            const flag = spec.flags.find((entry) => entry.name === name);
+            if (!flag) {
+                throw new UsageError(`unknown flag --${name}`, validFlagsHint(spec));
+            }
+            if (flag.type === "boolean") {
+                if (inline !== undefined) {
+                    throw new UsageError(`flag --${name} does not take a value`, validFlagsHint(spec));
+                }
+                flags[name] = true;
+                continue;
+            }
+            let value = inline;
+            if (value === undefined) {
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith("--")) {
+                    throw new UsageError(`flag --${name} requires a value`, `usage: --${name} <value>`);
+                }
+                value = next;
+                i += 1;
+            }
+            if (flag.values && !flag.values.includes(value)) {
+                throw new UsageError(`invalid value '${value}' for --${name}`, `valid values: ${flag.values.join(", ")}`);
+            }
+            flags[name] = value;
+            continue;
+        }
+        positionals.push(token);
+    }
+    if (!help) {
+        for (const arg of spec.args ?? []) {
+            if (arg.required && positionals.length === 0) {
+                throw new UsageError(`missing argument <${arg.name}>`, `usage: ip-axi ${spec.name} <${arg.name}>`);
+            }
+        }
+    }
+    return { positionals, flags, help };
+}
+export function stringFlag(parsed, name) {
+    const value = parsed.flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+export function booleanFlag(parsed, name) {
+    return parsed.flags[name] === true;
+}
+export function numberFlag(parsed, name, fallback) {
+    const raw = stringFlag(parsed, name);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 1) {
+        throw new UsageError(`--${name} must be a positive number`, `got '${raw}'`);
+    }
+    return Math.floor(value);
+}
+//# sourceMappingURL=args.js.map

package/dist/src/axi/args.js.map

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

package/dist/src/axi/boot.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Bootstrap runs before the CLI imports config, because provider credentials are
+// read once at module load. Keys already in the environment win; otherwise the
+// same MCP config that agents use supplies them, so the shell interface behaves
+// like an MCP client instead of requiring a second copy of every secret.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function seedFromMcpConfig() {
+    try {
+        const config = JSON.parse(readFileSync(join(homedir(), ".agents", "mcp.json"), "utf8"));
+        const env = config.mcpServers?.["ip-search-mcp"]?.env;
+        if (!env)
+            return;
+        for (const [name, value] of Object.entries(env)) {
+            if (value && !process.env[name])
+                process.env[name] = value;
+        }
+    }
+    catch {
+        // Missing or unreadable config is not fatal; the CLI reports unconfigured providers.
+    }
+}
+seedFromMcpConfig();
+await import("./index.js");
+//# sourceMappingURL=boot.js.map

package/dist/src/axi/boot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.js","sourceRoot":"","sources":["../../../src/axi/boot.ts"],"names":[],"mappings":";AACA,iFAAiF;AACjF,+EAA+E;AAC/E,gFAAgF;AAChF,yEAAyE;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAErF,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC;QACtD,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC7D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qFAAqF;IACvF,CAAC;AACH,CAAC;AAED,iBAAiB,EAAE,CAAC;AACpB,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC"}

package/dist/src/axi/client.js

@@ -0,0 +1,58 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createServer } from "../server.js";
+import { AxiError } from "./errors.js";
+let session;
+let live;
+async function connect() {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const server = createServer();
+    await server.connect(serverTransport);
+    const client = new Client({ name: "ip-axi", version: "0.1.0" });
+    await client.connect(clientTransport);
+    live = { client, server };
+    return client;
+}
+export function getClient() {
+    if (!session)
+        session = connect();
+    return session;
+}
+function textOf(content) {
+    if (!Array.isArray(content) || content.length === 0)
+        return "";
+    const first = content[0];
+    if (first === null || typeof first !== "object" || !("text" in first))
+        return "";
+    const text = first.text;
+    return typeof text === "string" ? text : "";
+}
+/** Call an MCP tool in-process and return its JSON payload. */
+export async function callTool(name, args) {
+    const client = await getClient();
+    const result = await client.callTool({ name, arguments: args });
+    const text = textOf(result.content);
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new AxiError(`${name} returned a non-JSON payload`, text.slice(0, 200));
+    }
+    if (result.isError) {
+        const record = payload;
+        throw new AxiError(record.message ?? `${name} failed`, record.hint);
+    }
+    return payload;
+}
+/** Close the in-process MCP session before exiting so libuv handles drain. */
+export async function shutdown() {
+    if (!live)
+        return;
+    const current = live;
+    live = undefined;
+    session = undefined;
+    await current.client.close().catch(() => undefined);
+    await current.server.close().catch(() => undefined);
+}
+//# sourceMappingURL=client.js.map

package/dist/src/axi/client.js.map

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