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 +64 -4
- package/dist/chunk-RXWXHORG.js +1016 -0
- package/dist/http.js +5 -3
- package/dist/registry.js +1 -1
- package/dist/stdio.js +5 -3
- package/package.json +5 -2
- package/dist/chunk-M5FQI2AW.js +0 -619
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
|
-
|
|
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
|
-
|
|
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
|
|
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.
|