@dialpad/dialtone-mcp-server 1.9.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 +33 -97
  2. package/RETRIEVAL.md +7 -1
  3. package/build/index.js +51650 -2488
  4. package/package.json +3 -3
package/README.md CHANGED
@@ -10,95 +10,38 @@ Set `DIALTONE_PROJECT_ROOT` to an absolute application dependency directory to s
10
10
 
11
11
  ## Installation
12
12
 
13
- There are three ways to install the Dialtone MCP Server. **Project-scoped installation takes priority** over user-scoped when both exist.
14
-
15
- ### Project-Scoped (Recommended for Teams)
16
-
17
- Best for team collaboration - everyone uses the same version via version control.
13
+ Install a locked project dependency from the application directory:
18
14
 
19
15
  ```bash
20
- npm install -D @dialpad/dialtone-mcp-server
21
- ```
22
-
23
- Create or update `.mcp.json` in your project root:
24
-
25
- ```json
26
- {
27
- "mcpServers": {
28
- "dialtone": {
29
- "command": "dialtone-mcp-server"
30
- }
31
- }
32
- }
16
+ npm install --save-dev --save-exact @dialpad/dialtone-mcp-server
33
17
  ```
34
18
 
35
- Commit `.mcp.json` to version control. Restart Claude Code to connect.
36
-
37
- **Priority:** Project-scoped beats user-scoped. The `dialtone-mcp-server` command resolves from `node_modules/.bin/` first.
38
-
39
- ### User-Scoped (Personal, All Projects)
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.
40
20
 
41
- Available across all your projects. Choose one method:
42
-
43
- **Option A: Install locally in your user directory**
44
-
45
- ```bash
46
- # Install in a dedicated directory
47
- mkdir -p ~/.mcp-servers
48
- cd ~/.mcp-servers
49
- npm install @dialpad/dialtone-mcp-server
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.
50
22
 
51
- # Add to Claude Code
52
- claude mcp add dialtone --scope user dialtone-mcp-server
53
- ```
54
-
55
- **Option B: Install globally**
56
-
57
- ```bash
58
- npm install -g @dialpad/dialtone-mcp-server
59
- claude mcp add dialtone --scope user dialtone-mcp-server
60
- ```
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.
61
24
 
62
- **Option C: Use npx (no installation)**
63
-
64
- ```bash
65
- claude mcp add dialtone --scope user -- npx -y @dialpad/dialtone-mcp-server
66
- ```
67
-
68
- This stores configuration in `~/.claude/mcp.json`.
69
-
70
- **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.
71
26
 
72
27
  ## Updating
73
28
 
74
- **Project-scoped:**
29
+ From the project installation directory:
75
30
 
76
31
  ```bash
77
- npm install -D @dialpad/dialtone-mcp-server@latest
32
+ npm install --save-dev --save-exact @dialpad/dialtone-mcp-server@latest
78
33
  ```
79
34
 
80
- **User-scoped (local directory):**
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.
81
36
 
82
- ```bash
83
- cd ~/.mcp-servers
84
- npm update @dialpad/dialtone-mcp-server
85
- ```
86
-
87
- **User-scoped (global):**
88
-
89
- ```bash
90
- npm update -g @dialpad/dialtone-mcp-server
91
- ```
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.
92
38
 
93
- **User-scoped (npx):**
94
-
95
- No action needed - npx always uses the latest version.
96
-
97
- 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).
98
40
 
99
41
  ## What You Can Search
100
42
 
101
- ### 1. Utility Classes (3,315 classes)
43
+ ### 1. Utility Classes
44
+
102
45
  Find CSS utility classes for styling HTML elements.
103
46
 
104
47
  **Example queries:**
@@ -108,7 +51,8 @@ Find CSS utility classes for styling HTML elements.
108
51
  - `margin top auto` → d-mt-auto
109
52
  - `text align center` → d-ta-center
110
53
 
111
- ### 2. Design Tokens (5,691 tokens)
54
+ ### 2. Design Tokens
55
+
112
56
  Search for design tokens (CSS variables).
113
57
 
114
58
  **Example queries:**
@@ -117,15 +61,17 @@ Search for design tokens (CSS variables).
117
61
  - `font family` → --dt-font-family-body, --dt-font-family-expressive
118
62
  - `font weight bold` → --dt-font-weight-bold
119
63
 
120
- ### 3. Components (87 components)
64
+ ### 3. Components
65
+
121
66
  Discover Vue components with props, events, and slots.
122
67
 
123
68
  **Example queries:**
124
- - `button` → DtButton, DtButtonGroup, DtBanner (29 results)
125
- - `modal` → DtModal, DtBanner, DtDropdown (6 results)
69
+ - `button` → DtButton, DtButtonGroup, DtBanner
70
+ - `modal` → DtModal, DtBanner, DtDropdown
126
71
  - `checkbox` → DtCheckbox, DtCheckboxGroup, DtRadio
127
72
 
128
- ### 4. Icons (594 icons)
73
+ ### 4. Icons
74
+
129
75
  Find icons from Dialtone's icon library.
130
76
 
131
77
  **Example queries:**
@@ -136,27 +82,15 @@ Find icons from Dialtone's icon library.
136
82
 
137
83
  ## Troubleshooting
138
84
 
139
- **Version check shows old version:**
140
- - Restart your Claude Code conversation after updating
141
- - 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.
142
88
 
143
89
  **MCP server not connecting:**
144
-
145
- For project-scoped:
146
- 1. Verify `.mcp.json` is in your project root with correct format
147
- 2. Check package is installed: `npm list @dialpad/dialtone-mcp-server`
148
- 3. Verify bin command exists: `ls node_modules/.bin/dialtone-mcp-server`
149
- 4. Restart Claude Code completely
150
-
151
- For user-scoped:
152
- 1. List configured servers: `claude mcp list`
153
- 2. Check if dialtone is listed and enabled
154
- 3. Test the server: `claude mcp get dialtone`
155
- 4. Check configuration: `cat ~/.claude/mcp.json`
156
-
157
- General:
158
- - Check Claude Code logs for connection errors
159
- - 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.
160
94
 
161
95
  ## Resources
162
96
 
@@ -225,9 +159,11 @@ node packages/dialtone-mcp-server/test-search.js
225
159
 
226
160
  Expected: `Overall Success Rate: 100%` (77/77 tests)
227
161
 
228
- ### 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.
229
165
 
230
- 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):
231
167
 
232
168
  ```json
233
169
  {
@@ -245,7 +181,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (MacOS)
245
181
  **Important:**
246
182
  - Use the absolute path to your dialtone repo
247
183
  - Restart Claude Desktop completely after updating the config
248
- - Look for the 🔌 icon to confirm connection
184
+ - Check client status and available tools after restarting
249
185
 
250
186
  **Finding your absolute path:**
251
187
  ```bash
package/RETRIEVAL.md CHANGED
@@ -12,7 +12,13 @@ Component searches preserve the existing first-five-prop sample, sampled event/s
12
12
 
13
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
14
 
15
- The selected `examples/button-default` and `examples/button-disabled-tooltip` records contain five complete application files, source qualification and validation metadata. 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.
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.
16
22
 
17
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.
18
24