@dialpad/dialtone-mcp-server 1.5.0 → 1.7.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.
Files changed (4) hide show
  1. package/README.md +15 -2
  2. package/RETRIEVAL.md +23 -0
  3. package/build/index.js +54153 -20992
  4. package/package.json +10 -6
package/README.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides AI assistants with search access to Dialtone's design system: utility classes, design tokens, Vue components, and icons.
4
4
 
5
- Automatically filters deprecated items, swaps discouraged patterns with recommended alternatives, and provides AI-optimized search results.
5
+ Filters deprecated items from general discovery, retains exact legacy-name matches with migration guidance, swaps discouraged patterns with recommended alternatives, and provides AI-optimized search results.
6
+
7
+ See [the retrieval contract](./RETRIEVAL.md) for readable searches, structured component/API and prose detail, compatible search inputs, provenance and continuation. Searches return Markdown text; only the two selected detail tools advertise structured output.
6
8
 
7
9
  ## Installation
8
10
 
@@ -63,7 +65,7 @@ claude mcp add dialtone --scope user -- npx -y @dialpad/dialtone-mcp-server
63
65
 
64
66
  This stores configuration in `~/.claude/mcp.json`.
65
67
 
66
- **Version checking:** When the server starts, you'll see the current version. If outdated, follow the instructions shown.
68
+ **Version checking:** The server connects to stdio before checking npm for updates. The advisory check is cancelled after two seconds or on shutdown. Offline, failed, or malformed registry replies are ignored. Valid version notices appear on stderr, keeping stdout available for MCP messages. On stdin EOF, SIGINT, or SIGTERM, the server closes its transport, flushes queued output, and exits even if an aborted registry connection retains a handle.
67
69
 
68
70
  ## Updating
69
71
 
@@ -194,6 +196,17 @@ npx tsx packages/dialtone-mcp-server/interactive-search.ts
194
196
 
195
197
  ### Run Tests
196
198
 
199
+ Startup and shutdown regressions build the server and its prerequisites first:
200
+
201
+ ```bash
202
+ pnpm nx run dialtone-mcp-server:test-startup
203
+ ```
204
+
205
+ From the package directory, `pnpm run test:startup` invokes `node --test` directly
206
+ and requires an existing server build. Use the Nx target above to build first.
207
+ Release-path regressions run with `pnpm run test:release-paths`.
208
+ Both regression suites run in the path-filtered Unit Tests workflow.
209
+
197
210
  From the package directory:
198
211
  ```bash
199
212
  cd packages/dialtone-mcp-server
package/RETRIEVAL.md ADDED
@@ -0,0 +1,23 @@
1
+ # MCP retrieval contract
2
+
3
+ The five `search_*` tools return readable Markdown text only. They do not advertise `outputSchema` or return `structuredContent`. Search results retain the shared domain formatters' facts and search notes: every utility property and usage, three token theme samples and usage, component descriptions and sampled API/import hints, icon categories/keywords/component imports, and documentation excerpts/links. Each page appends its matched/returned counts, bundled source package/version/exact artifact SHA256, and an explicit statement that installed compatibility is not checked.
4
+
5
+ All searches advertise and execute a default `limit` of 15. Queries are plain strings; additional arguments are accepted. Fractional numeric limits and harmless numeric strings retain the existing array-slice behavior, and zero retains the default of 15. Search limits are not reduced by a token budget. Whitespace-only queries return an explicit no-match message without an error. Long queries reach the existing domain search; documentation search retains its own truncation and notes. There is no new global query-length or matching rule.
6
+
7
+ `offset` is opt-in record pagination, defaults to zero and accepts integers from 0 to 100000. Follow the readable `Continue` call for the next page in the same search order. Later search pages label the page count against the total and continue result numbering; calls without an offset retain the existing formatter output. Continuations advance by the number of returned records and are omitted when they cannot make progress within the supported range. Invalid `offset` values return text errors; unknown argument names are ignored. There is no utility-property projection because utility text already contains every property of each returned class.
8
+
9
+ Token summaries preserve three named theme samples, explicitly label them as incomplete, and provide exact `search_tokens` follow-ups. Use `{ "query": "--dt-color-foreground-primary", "projection": "themes" }` to read complete named source theme records as Markdown. This opt-in projection uses the same limit/offset paging and includes all available migration metadata. It requires an exact source name; broad, missing and inherited names receive a no-match message with a summary route. Theme samples and detail values do not identify the active installed theme.
10
+
11
+ Component searches preserve the existing first-five-prop sample, sampled event/slot names, available value samples, descriptions and import hints. The adapter labels this API as incomplete and supplies `get_component` calls. Use a canonical name or unique alias to select one component: `{ "component": "DtButton", "projection": "props", "field": "kind" }` returns the complete available property record, including values, defaults and deprecation tags. Projections are `all` (default), `props`, `events`, `slots`, `methods` and `expose`. Missing metadata remains unknown; selection never substitutes a feature-search candidate.
12
+
13
+ Documentation search retains its readable excerpts and links, then supplies exact section IDs and `get_documentation` calls. For example, `{ "id": "components/checkbox#accessibility" }` retrieves available accessibility prose beyond the search excerpt. Follow the returned `textOffset` continuation for remaining content. Text offsets count Unicode code points. This corpus contains prose; example code requires separate verification.
14
+
15
+ Only `get_component` and `get_documentation` advertise structured output. Their C2 schema version 1 envelopes appear in `structuredContent` and in a text fallback containing the same JSON facts: match state, selected identity, source, counts, omissions and continuation. Their selectors remain trimmed nonempty strings of at most 256 characters, and their schemas reject unknown fields. Component detail accepts integer limits 1–50 (default 20) and record offsets 0–100000. Documentation detail accepts text limits 1–10000 (default 6000) and text offsets 0–1000000. Invalid detail arguments return an error envelope. `truncation.truncated` reports remaining records, remaining prose or other recorded omissions; reaching the final page alone does not mark a reply truncated.
16
+
17
+ These two selected detail tools retain a budget of 12000 estimated tokens, using `ceil(UTF-8 bytes of compact envelope JSON / 4)`. This is a rough estimate, not a model tokenizer or measured saving. Component records stay intact; allowed values, payloads and scoped bindings are never silently sliced. An oversized atomic contract reports `unavailable` and `atomic_contract_exceeds_budget`; request a narrower projection or named field. No continuation is emitted if it cannot make progress. This budget does not constrain readable searches or token-theme text pages.
18
+
19
+ Structured detail sources report bundled selection and `installedCompatibility: not_checked`. Each domain includes package/version/schema, `hash` (SHA256 of exact artifact bytes), and `contentHash` (SHA256 of canonically ordered JSON with only the declared repository prefix removed from `sourceFiles`, retaining semantic directories). `buildHash` combines domain content identities and package/schema versions. Raw hashes can differ across checkout paths; normalized identity remains stable when declared repository prefixes alone differ. Stamps contain no timestamp or absolute build path. Hash equality identifies data; it does not prove correctness or consumer availability.
20
+
21
+ Import hints verify stated exports only; they do not establish installed runtime imports, peers or compatibility. Documentation links come from authored API references and literal companions joined through public component identities and VuePress routes. They identify latest production references with readiness and API-content verification stated separately. Missing associations have no invented URL; conflicting associations have no asserted primary URL. Migration advice stays separate from a component's documentation page. Deployed availability and API completeness require separate verification.
22
+
23
+ Initialization instructions describe readable summaries, selected detail, continuation and source qualification within 100 words, with essential routing in the first 512 characters. The existing `dialtone://client-rules` resource remains available. SDK protocol checks do not establish automatic consumption by a named assistant client.