parseapi-mcp 0.4.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,13 +47,15 @@ CI and headless setups skip the browser with a key from [parseapi.com](https://p
47
47
 
48
48
  ## API versions
49
49
 
50
- The team's API version is selected in [Dashboard → API version](https://parseapi.com/dashboard/versions). One setting applies to every key and connected app in the team. Existing teams keep `1.0.0`; new teams start on `2.0.0`. Owners and admins can change it after reviewing and testing the target contract. Keys and app identities stay the same. Signing in or upgrading MCP does not change the team's version.
50
+ Since version 1.0.0, the package explicitly selects the API contract supported by this MCP package. Every API tool request sends `Parse-Version: 2.0.0`, matching this release's tool descriptions and SDK response types. The contract is fixed for both local stdio and hosted HTTP, including retries. Your key, OAuth identity and team's saved default stay the same.
51
51
 
52
- Published MCP/SDK `0.3.2` matches API `1.0.0`. This source tree's tool descriptions and SDK dependency expect API `2.0.0`; use a matching MCP release before changing the team's version. Test in a separate development team first; the change applies to all of the production team's integrations. The API returns the selected contract, so an upgrade can change the fields an agent receives. There is no version argument to add to tool calls. See [API versions and migration](https://parseapi.com/docs/versioning).
52
+ For local stdio, pin the MCP package version in your application configuration and test the new release before deploying it. A future major MCP upgrade can select a newer API contract. There is no version argument to add to individual tool calls. The hosted service uses the API contract supported by its deployed MCP release.
53
+
54
+ MCP packages older than 1.0.0 keep their existing behavior and use the team's default. Keep that default unchanged while older applications depend on it. Rolling back to a package without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged. See [API versions and migration](https://parseapi.com/docs/versioning).
53
55
 
54
56
  ## Tools
55
57
 
56
- 58 local tools and 57 hosted tools cover the lookup operations. `ip_self` is local only. `time` returns current local time and Unix seconds. It accepts a timezone or coordinates and defaults to UTC when both are omitted. `date` parses the supplied date, or returns today in UTC when omitted. Existing `timezone` calls remain supported with their original arguments. Every tool returns the JSON the API serves.
58
+ Full mode provides 58 local lookup tools and 57 hosted lookup tools, plus `discover` for local metadata and `preflight` for authenticated task estimates. `ip_self` is local only. `time` returns current local time and Unix seconds. It accepts a timezone or coordinates and defaults to UTC when both are omitted. `date` parses the supplied date, or returns today in UTC when omitted. Existing `timezone` calls remain supported with their original arguments. Every lookup returns the JSON the API serves.
57
59
 
58
60
  Tools follow the lookup names: `country_states`, `city_search`, `postal_nearby`, `address`, `address_search`, `company`, `email`, `vat`, `iban`, `bin`, `npi`, `vin`, `naics`, `naics_search`, `tariff`, `dns`, `asn`, `mac`, `currency_rate`, and the rest. All search tools take `query`.
59
61
 
@@ -85,6 +87,61 @@ Ordinary lookups retry up to twice after a transient failure. Metered lookups an
85
87
 
86
88
  Errors come back as JSON with a machine-readable `code`. Branch on `code`, never on message text. A miss is `not_found`. No key is `invalid_api_key`.
87
89
 
90
+ ## Agent discovery
91
+
92
+ Ask `discover` what an operation can determine before making a lookup:
93
+
94
+ ```json
95
+ { "operation": "email" }
96
+ ```
97
+
98
+ The result includes the actual input schema and reviewed policies for capabilities, freshness, uncertainty, billing units, credential types and retries. Both JSON text and MCP `structuredContent` carry the same result. Email, Domain, DNS, MX and Country have reviewed policies. Other operations return their input schema with `policy: null`. Field meanings are specific to each operation. An unknown result is not automatically a reason to retry.
99
+
100
+ Use `{ "query": "mailbox" }` to find operations. Search returns up to five summaries by default. `detail: "full"` includes schemas and policies. Use `limit` and the returned `next_offset` to page through results. Metadata calls make no API requests and consume no lookup units. Hosted HTTP still requires its existing authentication before discovery.
101
+
102
+ Policies describe the API contract. `effective_access: "not_evaluated"` and `pricing: "not_quoted"` mean discovery has not inspected the credential's permissions, remaining allowances or accepted rates. Use `preflight` for those account-specific estimates. A read-only lookup can still consume a paid unit.
103
+
104
+ Call `preflight` with a secret key and operation counts before spending:
105
+
106
+ ```json
107
+ {
108
+ "operations": [{ "operation": "email", "count": 100, "deep": true }],
109
+ "budget_usd": "2.50"
110
+ }
111
+ ```
112
+
113
+ Preflight supports Email, Domain, DNS, MX and Country, with up to 20 rows and 100,000 total lookups. It needs no lookup inputs or personal data. Check `permitted`, `cost.status`, `capacity` and `budget.within_maximum` together. Monetary values are decimal strings. The maximum assumes included Email checks are exhausted. The projection uses currently unallocated included checks. Unknowns stay null. Both use the credential's accepted rates.
114
+
115
+ The estimate allows up to three attempts per ordinary lookup and one per Email Deep lookup. Extra calls or retries require a new estimate. Capacity can change with concurrent work. Preflight reserves no units or money, performs no paid checks, and does not enforce the supplied budget. It uses the normal request rate limit. Subscription fees, tax and model costs are excluded. Preflight uses API contract 2.0.0 and the matching JavaScript SDK 1.1.0 or later.
116
+
117
+ For a compact tool catalog, set `PARSEAPI_MCP_MODE=compact` on the MCP process:
118
+
119
+ ```bash
120
+ PARSEAPI_MCP_MODE=compact npx -y parseapi-mcp@1.1.0
121
+ ```
122
+
123
+ Set `PARSEAPI_KEY` in the process environment for lookups. Compact mode advertises three tools, `discover`, `preflight` and `lookup`. After discovering an operation, pass its exact name and arguments:
124
+
125
+ ```json
126
+ { "operation": "country", "arguments": { "code": "US" } }
127
+ ```
128
+
129
+ `lookup` uses the same input validation, cancellation, version pin, SDK and billing behavior as the named tools. It executes one operation and cannot run arbitrary code or request arbitrary URLs. Full mode is the default and preserves existing named lookup calls. The same process setting supports self-hosted HTTP.
130
+
131
+ The policy source is the API's `src/route/help/agent-catalog.json`. Current API help exposes the same metadata as `agent`. Frozen API 1.0.0 help stays unchanged. In a ParseAPI workspace, run `npm run catalog:sync` to copy a reviewed policy change, then `npm run catalog:check`. An independent checkout can pass `-- --source /path/to/api`. Package builds use the checked-in copy and do not need the API checkout or a network request.
132
+
133
+ ## Display language
134
+
135
+ This source candidate adds optional `lang` to supported tools. For example,
136
+ `country` accepts `{"code":"DE","lang":"fr"}`. It requires a matching API
137
+ localization release, data, and JS SDK package; installing the existing published
138
+ package does not activate it.
139
+
140
+ Display names follow available source translations. IDs, native-name fields,
141
+ numbers and input parsing stay unchanged. Omitted language keeps the default
142
+ behavior. Measure parsing, currency rates, Holiday and prove tools have no new
143
+ language argument.
144
+
88
145
  ## Measurements
89
146
 
90
147
  Call `measure` with `{ "measure": "5 ft 11 in", "to": "cm" }`. The result keeps the amount as the decimal string `"180.34"`. Without `to`, the result uses the canonical unit for its type. Optional `locale` and `system` (`us` or `imperial`) resolve explicit number or customary-unit ambiguity.
@@ -97,12 +154,15 @@ Call `measure_units` with `{ "unit": "m" }` to discover compatible targets, or `
97
154
  npm install
98
155
  npm run typecheck
99
156
  npm test # builds and tests with mocked fetch and in-memory MCP
157
+ npm run eval:agents # offline benchmark self-test, no model or live API calls
100
158
  npm run smoke # stdio + http, includes live API authentication checks
101
159
  npm run serve # http on :8080
102
160
  ```
103
161
 
104
162
  Offline tests pin the public tool names and argument schemas in `test/public-api.json`, exercise every operation and query option, and verify errors, retries and cancellation. Review baseline changes as public API changes. Publishing runs typecheck and offline tests first.
105
163
 
164
+ The [agent benchmark](eval/README.md) compares full and compact discovery on fixed tasks with synthetic API responses. Its scripted reference run verifies the harness and grading, not agent completion quality. Model tokens and cost remain null until an adapter supplies measured usage. Fixture billing is simulated and always labeled separately from live charges.
165
+
106
166
  MIT licensed.
107
167
 
108
168
 
@@ -110,4 +170,4 @@ MIT licensed.
110
170
 
111
171
  Start with the default tool call. Use the same tool with `deep: true` for richer facts. Time, Date, Currency, Language, Emoji, Phone, IBAN and Point include detail on every plan. Geographic profiles, Name evidence and NAICS definitions require a paid plan. Carrier and HLR detail stays inside the same metered core unit, including Free allowance units, with no additional charge or second gate.
112
172
 
113
- Search detail belongs to each returned entity. Time conversion puts target display detail in `to.deep`; only the source returns `deep.next_dst`. Name core parsing needs no dictionary lookup. Country, State and Postal tax references are in their paid deep bags.
173
+ Search detail belongs to each returned entity. Time conversion puts target display detail in `to.deep`; only the source returns `deep.next_dst`. Name core parsing needs no dictionary lookup. Paid Name deep also returns flat `short`, `directory`, and `initials`. Optional `name_locale` selects CLDR formatting rules, defaults to `en`, and leaves parsing and gender context unchanged. Unavailable formatting is null, and older responses may omit these fields. Country, State and Postal tax references are in their paid deep bags.