@dialpad/dialtone-mcp-server 1.8.0 → 1.10.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 +38 -97
  2. package/RETRIEVAL.md +23 -3
  3. package/build/index.js +55727 -3115
  4. package/package.json +5 -5
package/README.md CHANGED
@@ -6,97 +6,42 @@ Filters deprecated items from general discovery, retains exact legacy-name match
6
6
 
7
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.
8
8
 
9
- ## Installation
10
-
11
- There are three ways to install the Dialtone MCP Server. **Project-scoped installation takes priority** over user-scoped when both exist.
12
-
13
- ### Project-Scoped (Recommended for Teams)
14
-
15
- Best for team collaboration - everyone uses the same version via version control.
16
-
17
- ```bash
18
- npm install -D @dialpad/dialtone-mcp-server
19
- ```
20
-
21
- Create or update `.mcp.json` in your project root:
22
-
23
- ```json
24
- {
25
- "mcpServers": {
26
- "dialtone": {
27
- "command": "dialtone-mcp-server"
28
- }
29
- }
30
- }
31
- ```
32
-
33
- Commit `.mcp.json` to version control. Restart Claude Code to connect.
34
-
35
- **Priority:** Project-scoped beats user-scoped. The `dialtone-mcp-server` command resolves from `node_modules/.bin/` first.
36
-
37
- ### User-Scoped (Personal, All Projects)
38
-
39
- Available across all your projects. Choose one method:
40
-
41
- **Option A: Install locally in your user directory**
9
+ Set `DIALTONE_PROJECT_ROOT` to an absolute application dependency directory to select installed lookup data. Without configuration, lookups stay bundled. See [installed project selection](./RETRIEVAL.md#installed-project-selection) for lookup boundaries, hoisting and restart behavior.
42
10
 
43
- ```bash
44
- # Install in a dedicated directory
45
- mkdir -p ~/.mcp-servers
46
- cd ~/.mcp-servers
47
- npm install @dialpad/dialtone-mcp-server
48
-
49
- # Add to Claude Code
50
- claude mcp add dialtone --scope user dialtone-mcp-server
51
- ```
11
+ ## Installation
52
12
 
53
- **Option B: Install globally**
13
+ Install a locked project dependency from the application directory:
54
14
 
55
15
  ```bash
56
- npm install -g @dialpad/dialtone-mcp-server
57
- claude mcp add dialtone --scope user dialtone-mcp-server
16
+ npm install --save-dev --save-exact @dialpad/dialtone-mcp-server
58
17
  ```
59
18
 
60
- **Option C: Use npx (no installation)**
19
+ Installation does not register a client connection. Follow the [MCP setup guide](https://dialtone.dialpad.com/guides/mcp-server/#installation) for Claude Code's `.mcp.json`/local/user scopes and Codex's complete user `config.toml` entry. It includes a package-manager runner and a resolved-entry alternative that handles hoisted installations. A bare local bin is not guaranteed to be on the client's PATH.
61
20
 
62
- ```bash
63
- claude mcp add dialtone --scope user -- npx -y @dialpad/dialtone-mcp-server
64
- ```
21
+ A launcher's cwd or prefix does not select installed data. Check a detail response's selected source/version and fallback reason after connecting.
65
22
 
66
- This stores configuration in `~/.claude/mcp.json`.
23
+ Keep existing trust, approvals and tool allowlists. Connection, raw server inventory, client-filtered exposure and actual tool calls are separate checks. Other clients, including the Claude Desktop development recipe below, need their own verification; no all-client compatibility claim is made here.
67
24
 
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.
25
+ For ongoing assistant use, merge the [shared lookup instruction](https://dialtone.dialpad.com/guides/getting-started/#ai-assisted-development) into a project file your client loads. It covers Claude Code/Codex loading routes and unavailable-tool behavior. The connected server supplies the MCP routing instructions during initialization; do not maintain a second routing sequence in project rules. Confirm actual lookup calls and selected source/version in the consuming session.
69
26
 
70
27
  ## Updating
71
28
 
72
- **Project-scoped:**
73
-
74
- ```bash
75
- npm install -D @dialpad/dialtone-mcp-server@latest
76
- ```
77
-
78
- **User-scoped (local directory):**
79
-
80
- ```bash
81
- cd ~/.mcp-servers
82
- npm update @dialpad/dialtone-mcp-server
83
- ```
84
-
85
- **User-scoped (global):**
29
+ From the project installation directory:
86
30
 
87
31
  ```bash
88
- npm update -g @dialpad/dialtone-mcp-server
32
+ npm install --save-dev --save-exact @dialpad/dialtone-mcp-server@latest
89
33
  ```
90
34
 
91
- **User-scoped (npx):**
35
+ Review and commit the manifest/lockfile change. Update a dedicated personal installation in its directory; use `npm install -g @dialpad/dialtone-mcp-server@latest` for a global one. `npx` can use a local or cached package or download one; it does not guarantee the latest release. Update any configured version pin deliberately.
92
36
 
93
- No action needed - npx always uses the latest version.
37
+ If your startup notice suggests a project-dev install without `--save-exact`, use the command for your installation mode above to preserve the intended pin and installation directory.
94
38
 
95
- After updating, restart your Claude Code conversation to pick up the new version.
39
+ Restart the server or reconnect/restart the client after package, configuration or Dialtone dependency changes. A new conversation alone may reuse the old process. The advisory startup check does not install updates and writes notices to stderr, preserving MCP stdout. See [updates and connection checks](https://dialtone.dialpad.com/guides/mcp-server/#configuration).
96
40
 
97
41
  ## What You Can Search
98
42
 
99
- ### 1. Utility Classes (3,315 classes)
43
+ ### 1. Utility Classes
44
+
100
45
  Find CSS utility classes for styling HTML elements.
101
46
 
102
47
  **Example queries:**
@@ -106,7 +51,8 @@ Find CSS utility classes for styling HTML elements.
106
51
  - `margin top auto` → d-mt-auto
107
52
  - `text align center` → d-ta-center
108
53
 
109
- ### 2. Design Tokens (5,691 tokens)
54
+ ### 2. Design Tokens
55
+
110
56
  Search for design tokens (CSS variables).
111
57
 
112
58
  **Example queries:**
@@ -115,15 +61,17 @@ Search for design tokens (CSS variables).
115
61
  - `font family` → --dt-font-family-body, --dt-font-family-expressive
116
62
  - `font weight bold` → --dt-font-weight-bold
117
63
 
118
- ### 3. Components (87 components)
64
+ ### 3. Components
65
+
119
66
  Discover Vue components with props, events, and slots.
120
67
 
121
68
  **Example queries:**
122
- - `button` → DtButton, DtButtonGroup, DtBanner (29 results)
123
- - `modal` → DtModal, DtBanner, DtDropdown (6 results)
69
+ - `button` → DtButton, DtButtonGroup, DtBanner
70
+ - `modal` → DtModal, DtBanner, DtDropdown
124
71
  - `checkbox` → DtCheckbox, DtCheckboxGroup, DtRadio
125
72
 
126
- ### 4. Icons (594 icons)
73
+ ### 4. Icons
74
+
127
75
  Find icons from Dialtone's icon library.
128
76
 
129
77
  **Example queries:**
@@ -134,27 +82,15 @@ Find icons from Dialtone's icon library.
134
82
 
135
83
  ## Troubleshooting
136
84
 
137
- **Version check shows old version:**
138
- - Restart your Claude Code conversation after updating
139
- - The server loads once at conversation start
85
+ **Version check shows an old version:**
86
+ - Check the actual package selected by the configured runner or entry path.
87
+ - Restart the server/client after updating; a new conversation may reuse a process.
140
88
 
141
89
  **MCP server not connecting:**
142
-
143
- For project-scoped:
144
- 1. Verify `.mcp.json` is in your project root with correct format
145
- 2. Check package is installed: `npm list @dialpad/dialtone-mcp-server`
146
- 3. Verify bin command exists: `ls node_modules/.bin/dialtone-mcp-server`
147
- 4. Restart Claude Code completely
148
-
149
- For user-scoped:
150
- 1. List configured servers: `claude mcp list`
151
- 2. Check if dialtone is listed and enabled
152
- 3. Test the server: `claude mcp get dialtone`
153
- 4. Check configuration: `cat ~/.claude/mcp.json`
154
-
155
- General:
156
- - Check Claude Code logs for connection errors
157
- - Remember: Project-scoped configuration overrides user-scoped
90
+ 1. Check the client-specific configuration and its selected scope. Claude Code uses project `.mcp.json` or local/user entries in `~/.claude.json`; Codex uses its TOML configuration.
91
+ 2. For a project or dedicated installation, run `npm ls @dialpad/dialtone-mcp-server` from its installation directory; use `npm ls -g @dialpad/dialtone-mcp-server` for a global installation. For `npx`, check the connected server version; `npm ls` does not identify a cached selection. A workspace may hoist the package outside the application's own `node_modules`.
92
+ 3. Inspect client status/logs and available tools. `claude mcp list` and `claude mcp get dialtone` inspect registration and can health-check a server; Codex has its own MCP status. Neither proves model tool selection.
93
+ 4. Check absolute installed-data roots and the selected source/fallback in a detail reply. Preserve existing trust, permission and exposure settings.
158
94
 
159
95
  ## Resources
160
96
 
@@ -204,6 +140,9 @@ pnpm nx run dialtone-mcp-server:test-startup
204
140
 
205
141
  From the package directory, `pnpm run test:startup` invokes `node --test` directly
206
142
  and requires an existing server build. Use the Nx target above to build first.
143
+ Protocol checks likewise build first with `pnpm nx run dialtone-mcp-server:test-protocol`.
144
+ The package-level `pnpm run test:protocol` is a direct Node/tsx runner and requires
145
+ a current build; CI builds both adapters before invoking it.
207
146
  Release-path regressions run with `pnpm run test:release-paths`.
208
147
  Both regression suites run in the path-filtered Unit Tests workflow.
209
148
 
@@ -220,9 +159,11 @@ node packages/dialtone-mcp-server/test-search.js
220
159
 
221
160
  Expected: `Overall Success Rate: 100%` (77/77 tests)
222
161
 
223
- ### Configure with Claude Desktop (for testing)
162
+ ### Configure with Claude Desktop (development reference)
163
+
164
+ This recipe has not been verified in a Claude Desktop session. For the repository build, build the server first and use its actual absolute entry path. Follow the client's current setup instructions; the locations below are client-specific, not Claude Code configuration.
224
165
 
225
- Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (MacOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
166
+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
226
167
 
227
168
  ```json
228
169
  {
@@ -240,7 +181,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (MacOS)
240
181
  **Important:**
241
182
  - Use the absolute path to your dialtone repo
242
183
  - Restart Claude Desktop completely after updating the config
243
- - Look for the 🔌 icon to confirm connection
184
+ - Check client status and available tools after restarting
244
185
 
245
186
  **Finding your absolute path:**
246
187
  ```bash
package/RETRIEVAL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # MCP retrieval contract
2
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.
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, selected source package/version/exact artifact SHA256, and an explicit statement that installed compatibility is not checked.
4
4
 
5
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
6
 
@@ -10,14 +10,34 @@ Token summaries preserve three named theme samples, explicitly label them as inc
10
10
 
11
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
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.
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. Reference excerpts may contain code fragments; these do not establish complete runnable examples.
14
+
15
+ Use `get_documentation({"id":"examples/toggle-base-styles","projection":"context"})` for compact source/sibling sections, authored API subjects, explicit directives/utilities and documentation links. An exact page `docId` is also accepted in this projection. Context uses reference `limit` 1–50 (default 20) and `offset` 0–100000 (default 0), the existing detail budget and whole-reference continuation. It returns no target prose or runnable files. Follow documentation IDs with `get_documentation`, component names with `get_component`, utilities with `search_utility_classes`, and a link's `targetDocId` with `get_documentation` context. A preset's synthetic provenance is not a documentation selector.
16
+
17
+ Content detail includes a compact `contextRequest`; omitted projection keeps the current content/Unicode continuation contract. Non-default pagination for the other mode is rejected; echoed defaults are ignored. Unknown fields remain errors. References identify bundled authored context; installed API/CSS availability is determined by the follow-up lookup. Source URLs are latest references and missing links remain explicitly unresolved.
18
+
19
+ Ready public component-page Vue demos are delivered automatically when public imports and supported state resolve and the source API check passes. Default IDs use `examples/docs/<docId>/<section-slug>`, with source identity overrides for earlier exact IDs and ambiguous headings. Removed or renamed IDs return no-match unless an explicit ID is retained. Other source forms remain outside this rule.
20
+
21
+ Documentation and curated Combinator preset records contain complete application files, source qualification and validation metadata; static utility records contain standalone HTML. This selection is not full coverage. See the [selected-example guide](https://dialtone.dialpad.com/guides/mcp-server/#retrieve-a-selected-example) for the available IDs. Subject-based component search and documentation source sections supply bounded IDs and `get_documentation` calls; exact source/component detail exposes the full exampleIds list. Unknown example IDs list available IDs and provide search recovery; ordinary documentation search excludes complete example records. Follow every returned text continuation before assembling files. Their `dt10-pinned` profile is umbrella 10.5.1, icons 5.2.0 and Vue 3.5.18, separately qualified from the documentation source version and installed data. Recorded build/API checks apply only to the identified payload hash; source or file changes invalidate them. Manual spot checks record the reviewer and browser/AT versions separately and apply only to the matching payload hash. Neither a build nor retrieval proves accessibility or installed-project compatibility.
14
22
 
15
23
  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
24
 
17
25
  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
26
 
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.
27
+ Structured detail sources report `bundled`, `installed` or `mixed` selection and `installedCompatibility: not_checked`. Each domain includes package/version/schema and `hash` (SHA256 of exact artifact bytes). Bundled domains also include `contentHash` (SHA256 of canonically ordered JSON with only the declared repository prefix removed from `sourceFiles`, retaining semantic directories). Installed domains omit this optional normalized hash because their repository prefix is unknown. Unversioned legacy formats report schema version 1; unsupported formats fall back explicitly. `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
28
 
21
29
  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
30
 
23
31
  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.
32
+
33
+ ## Installed project selection
34
+
35
+ `DIALTONE_PROJECT_ROOT` explicitly names the absolute application dependency root. Optional `DIALTONE_LOOKUP_ROOT` permits ancestor hoisting inside a bounded workspace. No client Roots request, implicit cwd selection, downward discovery, per-call path, watcher or protocol upgrade is involved. Separate applications use separate server instances. Configuration and dependencies are captured at startup; restart after changes.
36
+
37
+ In pnpm workspaces, and other layouts where package symlinks resolve outside the application folder, also set `DIALTONE_LOOKUP_ROOT` to the workspace root.
38
+
39
+ The Node-only query-core entry `@dialpad/dialtone-query-core/node` is shared with the CLI through compatibility re-exports. The default entry stays free of runtime filesystem imports; existing deep import paths remain available. CLI resolution remains unchanged. The MCP policy accepts declared packages only, gives the umbrella precedence, and confines package/data/entry realpaths to its authorized boundary and repository. It preserves unknown legacy fields, rejects malformed or unsupported datasets and falls back per domain. Bundled fallback retains source-verified metadata/imports without claiming installed verification. Missing export evidence is unverified; only a complete parsed installed entry can establish an unavailable export. An exported name with no metadata does not receive a fabricated API.
40
+
41
+ Each selected domain records its actual data SHA256, package version, installed/bundled selection and fallback reason. Documentation and its component-link catalog stay bundled/latest-qualified, with no fallback reason for these expected reference sources. Startup stderr and search/detail replies report installed-data failures and version-mismatch warnings. `buildHash` continues to identify the adapter's bundled build; per-domain hashes identify selected installed data. Resource payloads retain their JSON shape and use the same captured data as tools; `_meta.dialtone` records resource source and the unverified runtime-compatibility boundary. Client rules remain bundled policy, not a version-compatibility guarantee.
42
+
43
+ Workspace declarations are resolved from the application toward the explicit lookup root, stopping at Git boundaries. The closest manifest declaring Dialtone packages owns selection; declarations from separate applications are never combined.