parseapi-mcp 1.0.0 → 1.2.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,15 +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
- Version 1.0.0 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.
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
53
 
54
- Previously published MCP packages 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).
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).
55
55
 
56
56
  ## Tools
57
57
 
58
- 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.
59
59
 
60
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`.
61
61
 
@@ -87,6 +87,49 @@ Ordinary lookups retry up to twice after a transient failure. Metered lookups an
87
87
 
88
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`.
89
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.2.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.2.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
+
90
133
  ## Display language
91
134
 
92
135
  This source candidate adds optional `lang` to supported tools. For example,
@@ -111,12 +154,15 @@ Call `measure_units` with `{ "unit": "m" }` to discover compatible targets, or `
111
154
  npm install
112
155
  npm run typecheck
113
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
114
158
  npm run smoke # stdio + http, includes live API authentication checks
115
159
  npm run serve # http on :8080
116
160
  ```
117
161
 
118
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.
119
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
+
120
166
  MIT licensed.
121
167
 
122
168