@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.
- package/README.md +38 -97
- package/RETRIEVAL.md +23 -3
- package/build/index.js +55727 -3115
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
13
|
+
Install a locked project dependency from the application directory:
|
|
54
14
|
|
|
55
15
|
```bash
|
|
56
|
-
npm install -
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
32
|
+
npm install --save-dev --save-exact @dialpad/dialtone-mcp-server@latest
|
|
89
33
|
```
|
|
90
34
|
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
123
|
-
- `modal` → DtModal, DtBanner, DtDropdown
|
|
69
|
+
- `button` → DtButton, DtButtonGroup, DtBanner
|
|
70
|
+
- `modal` → DtModal, DtBanner, DtDropdown
|
|
124
71
|
- `checkbox` → DtCheckbox, DtCheckboxGroup, DtRadio
|
|
125
72
|
|
|
126
|
-
### 4. 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
|
-
-
|
|
139
|
-
-
|
|
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-
|
|
144
|
-
|
|
145
|
-
|
|
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 (
|
|
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` (
|
|
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
|
-
-
|
|
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,
|
|
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.
|
|
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
|
|
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.
|