feat: add gmail/websearch and bluebubbles toolcalls

.gitignore

@@ -8,3 +8,5 @@ dist
 *.db-*
 .netlify
 .vercel
+src/mastra/public/mastra.duckdb
+src/mastra/public/mastra.duckdb.wal

.nvmrc

@@ -0,0 +1 @@
+v24.14.0

README.md

@@ -12,6 +12,53 @@ npm run dev
 
 Open [http://localhost:4111](http://localhost:4111) in your browser to access [Mastra Studio](https://mastra.ai/docs/studio/overview). It provides an interactive UI for building and testing your agents, along with a REST API that exposes your Mastra application as a local service. This lets you start building without worrying about integration right away.
 
+Start the iMessage runtime webhook listener:
+
+```shell
+npm run start
+```
+
+`npm run dev` does not start the BlueBubbles webhook listener.
+
+## MCP Tool Integrations
+
+External MCP tools can be registered without writing custom Mastra tools.
+
+Add MCP servers to `~/.agent/config.json`:
+
+```json
+{
+  "mcp": {
+    "timeoutMs": 60000,
+    "servers": {
+      "gmail": {
+        "command": "npx",
+        "args": ["-y", "your-mcp-server-package"]
+      },
+      "docs": {
+        "url": "https://example.com/mcp",
+        "headers": {
+          "authorization": "Bearer token"
+        }
+      }
+    }
+  }
+}
+```
+
+You can also override via env vars:
+
+- `AGENT_MCP_SERVERS_JSON` (JSON object of server configs)
+- `AGENT_MCP_TIMEOUT_MS` (positive integer milliseconds)
+
+MCP tools are namespaced as `server_toolName` and composed with native tools (`web_search` and BlueBubbles tools).
+
+If your BlueBubbles password contains URL-reserved characters (for example `#`), use an encoded guid value in the webhook URL:
+
+```text
+?guid=<encodeURIComponent(password)>
+```
+
 You can start editing files inside the `src/mastra` directory. The development server will automatically reload whenever you make changes.
 
 ## Learn more
@@ -25,3 +72,10 @@ If you're new to AI agents, check out our [course](https://mastra.ai/course) and
 [Mastra Cloud](https://cloud.mastra.ai/) gives you a serverless agent environment with atomic deployments. Access your agents from anywhere and monitor performance. Make sure they don't go off the rails with evals and tracing.
 
 Check out the [deployment guide](https://mastra.ai/docs/deployment/overview) for more details.
+
+## TODO
+
+- Add Mastra evals for iMessage reply quality after the OpenClaw-style prompt flow settles.
+- Cover short-greeting behavior like `hi` / `hey` / `yo` and assert one short natural bubble.
+- Cover `[MSG]` behavior and assert delimiters never leak into sent text.
+- Cover multi-bubble timing and assert later bubbles are staggered enough to feel human.