ttp-agent-sdk 2.48.16 → 2.48.20

package/dist/index.html

@@ -23,7 +23,7 @@
           <img src="https://talktopc.com/logo192.png" alt="TTP Logo" style="width: 40px; height: 40px; border-radius: 8px;">
           <div>
             <h1 style="margin: 0; font-size: 1.4rem;">TTP Agent SDK</h1>
-            <p class="version" style="margin: 0;">v2.48.15</p>
+            <p class="version" style="margin: 0;">v2.48.16</p>
           </div>
         </div>
       </div>
@@ -62,6 +62,7 @@
             <li><a href="#widget-flavors" class="nav-link">Widget Flavors</a></li>
             <li><a href="#client-script-tools" class="nav-link">Client-Script Tools</a></li>
             <li><a href="#chain-tools" class="nav-link">Chain Tools</a></li>
+            <li><a href="#platform-mcp" class="nav-link">Platform MCP</a></li>
           </ul>
         </div>
 
@@ -153,6 +154,13 @@
                 <p>Backend SDK for server-side TTS</p>
                 <span class="quick-link-arrow">→</span>
               </a>
+
+              <a href="#platform-mcp" class="quick-link-card">
+                <div class="quick-link-icon">🤖</div>
+                <h3>Platform MCP</h3>
+                <p>Build agents from Cursor or Claude</p>
+                <span class="quick-link-arrow">→</span>
+              </a>
             </div>
           </div>
 
@@ -5258,6 +5266,108 @@ Files.write(Paths.get("output.wav"), response.getAudio());</code></pre>
             <li><strong>Examples:</strong> Check <code>src/main/java/com/talktopc/sdk/examples/</code></li>
           </ul>
         </section>
+
+        <section id="platform-mcp" class="doc-section">
+          <h1>Platform MCP</h1>
+          <p class="lead">The TalkToPC platform MCP lets Cursor, Claude, and other MCP clients create and edit voice agents on the control plane — prompts, tools, scripts, webhooks, knowledge bases, phonemes — without the dashboard.</p>
+
+          <div class="info-box">
+            <strong>For AI agents:</strong> the full playbook (connect, operating rules, workflows, every tool argument) is
+            <a href="mcp.md"><code>docs/mcp.md</code></a>. Read that file before calling tools.
+          </div>
+
+          <h2>What it is (and is not)</h2>
+          <p>This MCP talks to <code>backend.talktopc.com</code> and writes the same agent records the dashboard writes. After you change an agent, the <strong>SDK in this repo</strong> still connects with <code>agentId</code> + <code>appId</code> to <code>wss://speech.talktopc.com/ws/conv</code>.</p>
+          <ul>
+            <li><strong>URL:</strong> <code>https://mcp.talktopc.com/mcp</code></li>
+            <li><strong>Auth:</strong> developer API key <code>sk_…</code> from the dashboard <strong>Developers</strong> page</li>
+            <li><strong>Not</strong> the widget SDK, not the voice WebSocket, not the Gmail/Calendar MCP on port 3007</li>
+          </ul>
+
+          <h2>Connect</h2>
+          <h3>Claude.ai</h3>
+          <ol>
+            <li>Customize → Connectors → Add custom connector</li>
+            <li>URL: <code>https://mcp.talktopc.com/mcp</code></li>
+            <li>Leave OAuth Client ID / Secret <strong>empty</strong></li>
+            <li>Add → Connect → paste <code>sk_…</code> on the TalkToPC sign-in page</li>
+          </ol>
+          <p>Do not invent a Client ID. Claude registers itself; the sign-in page is how you hand over the key.</p>
+
+          <h3>Cursor / Claude Code</h3>
+          <pre><code>"ttp-platform": {
+  "command": "node",
+  "args": ["/absolute/path/to/ttp-platform-mcp/dist/stdio.js"],
+  "env": {
+    "TTP_API_KEY": "sk_…",
+    "TTP_BACKEND_URL": "https://backend.talktopc.com"
+  }
+}</code></pre>
+
+          <h3>Any HTTP client</h3>
+          <p><code>POST https://mcp.talktopc.com/mcp</code> with <code>Authorization: Bearer sk_…</code> (or <code>x-api-key</code>). <code>GET /mcp</code> is 405 on purpose. <code>GET /health</code> is public.</p>
+
+          <h2>Rules for agents using the tools</h2>
+          <ol>
+            <li>List / get before you write. Prefer <code>get_agent</code> <code>view=summary</code> or <code>view=section</code> over <code>full</code>.</li>
+            <li>Change fields with <code>patch_agent</code> dotted paths. Last write wins — do not patch the same agent in parallel.</li>
+            <li>Deletes require <code>confirm: true</code>.</li>
+            <li>Create library objects (tool / script / KB / webhook / phoneme set) first, then <code>attach_*</code>.</li>
+            <li>Pick <code>model</code> and <code>voiceId</code> from resources <code>talktopc://llm-models</code> and <code>talktopc://voices</code>.</li>
+            <li>MCP returns <code>agentid</code>. The widget still needs <code>appId</code> from the dashboard — MCP does not mint it.</li>
+            <li>Never print <code>sk_</code> keys or webhook <code>auth_token</code>s.</li>
+          </ol>
+
+          <h2>Typical flow</h2>
+          <pre><code>list_agents
+get_agent { agentId, view: "section", section: "systemPrompt" }
+patch_agent { agentId, changes: { "systemPrompt": "…" } }
+
+create_tool { toolData }
+attach_tool { agentId, toolId }
+
+create_kb { name: "FAQ" }
+add_doc { kbId, name: "Hours", source_type: "text", text: "…" }
+attach_kb { agentId, kbId }</code></pre>
+
+          <h2>Tool groups</h2>
+          <table class="properties-table">
+            <thead>
+              <tr>
+                <th>Group</th>
+                <th>Tools</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Agents</td>
+                <td><code>list_agents</code> <code>get_agent</code> <code>create_agent</code> <code>patch_agent</code> <code>delete_agent</code> <code>export_agent</code> <code>import_agent</code></td>
+              </tr>
+              <tr>
+                <td>Tools</td>
+                <td><code>list_tools</code> <code>get_tool</code> <code>create_tool</code> <code>update_tool</code> <code>delete_tool</code> <code>attach_tool</code> <code>detach_tool</code></td>
+              </tr>
+              <tr>
+                <td>Scripts</td>
+                <td><code>list_scripts</code> <code>get_script</code> <code>create_script</code> <code>update_script</code> <code>delete_script</code> <code>attach_script</code> <code>detach_script</code></td>
+              </tr>
+              <tr>
+                <td>Webhooks</td>
+                <td><code>list_webhooks</code> <code>get_webhook</code> <code>create_webhook</code> <code>update_webhook</code> <code>delete_webhook</code> <code>test_webhook</code> <code>set_call_summary</code></td>
+              </tr>
+              <tr>
+                <td>Knowledge</td>
+                <td><code>list_kbs</code> <code>create_kb</code> <code>get_kb</code> <code>delete_kb</code> <code>list_docs</code> <code>add_doc</code> <code>upload_doc</code> <code>delete_doc</code> <code>attach_kb</code> <code>detach_kb</code> <code>kb_limits</code> <code>search_kb</code></td>
+              </tr>
+              <tr>
+                <td>Phonemes</td>
+                <td><code>list_phoneme_sets</code> <code>get_phoneme_set</code> <code>create_phoneme_set</code> <code>add_phoneme_entry</code> <code>remove_phoneme_entry</code> <code>suggest_ipa</code> <code>delete_phoneme_set</code> <code>attach_phoneme_set</code></td>
+              </tr>
+            </tbody>
+          </table>
+
+          <p>Arguments, resources, clone/export flow, and failure cheatsheet: <a href="mcp.md">docs/mcp.md</a>.</p>
+        </section>
       </div>
 
       <!-- Footer -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttp-agent-sdk",
-  "version": "2.48.16",
+  "version": "2.48.20",
   "description": "Comprehensive Voice Agent SDK with Customizable Widget - Real-time audio, WebSocket communication, React components, and extensive customization options",
   "main": "dist/agent-widget.js",
   "module": "dist/agent-widget.esm.js",
@@ -40,6 +40,8 @@
     "test:compile-adapter": "node scripts/compile-adapter.test.mjs",
     "test:adapters": "npm run test:compile-adapter && npm run test:verify-adapter",
     "test:client-tools": "node --test test/client-tools-registry.test.mjs",
+    "test:hop": "node --test test/hop-platform.test.mjs",
+    "test:loopback": "node --test test/loopback-aec.test.mjs",
     "clean": "rm -rf dist/",
     "prebuild": "npm run clean"
   },