@routecraft/ai 0.3.0-canary.9 → 0.3.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 (2) hide show
  1. package/README.md +94 -57
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @routecraft/ai
2
2
 
3
- AI and MCP integrations for RouteCraft.
3
+ AI adapters and MCP integration for RouteCraft. Call LLMs, run agents, generate embeddings, and expose your capabilities to Claude, Cursor, and other MCP clients.
4
4
 
5
5
  ## Installation
6
6
 
@@ -16,30 +16,91 @@ pnpm add @routecraft/ai
16
16
 
17
17
  ## Quick Start
18
18
 
19
+ Define a capability and expose it as an MCP tool:
20
+
19
21
  ```typescript
22
+ // capabilities/fetch-webpage.ts
20
23
  import { mcp } from '@routecraft/ai';
21
- import { craft, simple, direct } from '@routecraft/routecraft';
24
+ import { craft, context, http } from '@routecraft/routecraft';
25
+ import { z } from 'zod';
22
26
 
23
- // In-process: use direct(); MCP server route needs description
24
- craft()
25
- .from(simple({ query: 'hello' }))
26
- .to(direct('my-tool'));
27
+ const ctx = context()
28
+ .routes([
29
+ craft()
30
+ .id('fetch-webpage')
31
+ .from(
32
+ mcp('fetch-webpage', {
33
+ description: 'Fetch and return the content of a webpage',
34
+ schema: z.object({ url: z.string().url() }),
35
+ })
36
+ )
37
+ .enrich(http({ url: (ex) => ex.body.url })),
38
+ ])
39
+ .build();
27
40
 
28
- craft()
29
- .from(mcp('my-tool', { description: 'My tool' }))
30
- .process((body) => body);
41
+ await ctx.start();
31
42
  ```
32
43
 
33
- ## Features
44
+ Run it as an MCP server:
45
+
46
+ ```bash
47
+ npx @routecraft/cli run capabilities/fetch-webpage.ts
48
+ ```
49
+
50
+ ## Two Modes
51
+
52
+ ### Server Mode: expose capabilities outward via MCP
53
+
54
+ Use `mcp()` as a `.from()` source. This registers the capability as an MCP tool that Claude Desktop, Cursor, or any MCP client can invoke.
55
+
56
+ ```typescript
57
+ import { mcp, llm, llmPlugin } from '@routecraft/ai';
58
+ import { craft, context, http } from '@routecraft/routecraft';
59
+ import { z } from 'zod';
60
+
61
+ const ctx = context()
62
+ .plugins([
63
+ llmPlugin({
64
+ providers: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } },
65
+ }),
66
+ ])
67
+ .routes([
68
+ craft()
69
+ .id('summarize-webpage')
70
+ .from(
71
+ mcp('summarize-webpage', {
72
+ description: 'Fetch and summarize the content of a webpage',
73
+ schema: z.object({ url: z.string().url() }),
74
+ })
75
+ )
76
+ .enrich(http({ url: (ex) => ex.body.url }))
77
+ .to(llm('anthropic:claude-sonnet-4-6', {
78
+ systemPrompt: 'Summarize the following webpage content concisely.',
79
+ userPrompt: (ex) => String(ex.body),
80
+ })),
81
+ ])
82
+ .build();
83
+ ```
84
+
85
+ ### Client Mode: route data to agents in code
34
86
 
35
- - **mcp()**: MCP server (`.from(mcp(endpoint, { description }))`) and client (`.to(mcp({ url, tool }))` or `.to(mcp('server:tool', { args }))`). For in-process use `direct()`.
36
- - **Discovery**: Tools register in the context store for querying endpoints, descriptions, and schemas
37
- - **Schema validation**: Use Zod (or other Standard Schema libs) for body and header validation on tools
38
- - **Coming soon**: LLM adapters (OpenAI, Gemini), MCP source/destination, agent routing
87
+ Use `mcp()` as a `.to()` destination to call another MCP server, or use `direct()` to call a capability in the same process by ID.
39
88
 
40
- ## Connecting from Cursor / Claude Desktop (MCP)
89
+ ```typescript
90
+ import { direct, timer } from '@routecraft/routecraft';
91
+
92
+ // Call a capability in the same process on a schedule
93
+ craft()
94
+ .id('orchestrator')
95
+ .from(timer({ intervalMs: 60_000 }))
96
+ .to(direct('fetch-webpage'));
97
+ ```
41
98
 
42
- **Recommended:** use **npx** so the MCP client runs the CLI without needing a global install or full paths. The server requires **Node.js 18.19+ or 20+** (Pino 10 needs `diagnostics_channel.tracingChannel`). If the client uses an older Node, start Cursor/Claude from a shell where a newer Node is first in `PATH` (e.g. `nvm use 22`), or set **command** to the full path of a Node 20+ binary and **args** with the path to the CLI entry (see fallback below).
99
+ ## Connecting Claude Desktop and Cursor
100
+
101
+ The CLI runs your capability file as an MCP server. Use `npx` so clients do not need a global install.
102
+
103
+ **Node.js 18.19+ or 20+** is required.
43
104
 
44
105
  In **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) or **Cursor** (MCP settings):
45
106
 
@@ -51,62 +112,38 @@ In **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_conf
51
112
  "args": [
52
113
  "@routecraft/cli",
53
114
  "run",
54
- "--log-file",
55
- "/path/to/craft.log",
56
- "--log-level",
57
- "debug",
58
- "/path/to/your/index.mjs"
115
+ "--log-file", "/path/to/craft.log",
116
+ "--log-level", "debug",
117
+ "/path/to/your/capabilities/index.ts"
59
118
  ]
60
119
  }
61
120
  }
62
121
  }
63
122
  ```
64
123
 
65
- Use `@routecraft/cli@canary` for the latest canary build. Logging to a file keeps stdout JSON-RPC-only; omit `--log-file` / `--log-level` or use `--log-level silent` to disable logs.
124
+ Use `@routecraft/cli@canary` for the latest canary build. Writing logs to a file keeps stdout JSON-RPC-only, which is required for MCP transport. Use `--log-level silent` to disable logs entirely.
66
125
 
67
- **Fallback (minimal PATH):** if `npx` is not available to the MCP client, set **command** to the full path of a Node 20+ binary and **args** so the first element is the CLI’s JavaScript entry. From a project with `@routecraft/cli` installed: `node -e "console.log(require.resolve('@routecraft/cli/dist/index.js'))"`.
126
+ **If `npx` is not available to the MCP client:** set `command` to the full path of a Node 20+ binary and set the first `args` element to the CLI entry point. From a project with `@routecraft/cli` installed, find it with:
68
127
 
69
- ## Documentation
128
+ ```bash
129
+ node -e "console.log(require.resolve('@routecraft/cli/dist/index.js'))"
130
+ ```
70
131
 
71
- For comprehensive documentation, examples, and guides, visit [routecraft.dev](https://routecraft.dev).
132
+ ## Features
72
133
 
73
- ## Example
134
+ - **`mcp(name, options)`**: Register a capability as an MCP tool (server mode) or call an external MCP server (client mode)
135
+ - **`llm(modelId, options?)`**: Call any LLM provider from a capability pipeline. Supports Anthropic, OpenAI, Gemini, Ollama, and OpenRouter. Register providers via `llmPlugin`.
136
+ - **`embedding(modelId, options?)`**: Generate embeddings from a capability pipeline.
137
+ - **Schema validation**: Use Zod (or any Standard Schema library) for strict input validation on MCP tools
138
+ - **Tool discovery**: Registered tools are available via the context store for querying endpoints, descriptions, and schemas
74
139
 
75
- ```typescript
76
- import { mcp } from '@routecraft/ai';
77
- import {
78
- craft,
79
- context,
80
- DirectAdapter,
81
- http,
82
- } from '@routecraft/routecraft';
83
- import { z } from 'zod';
84
-
85
- const ctx = context()
86
- .routes([
87
- craft()
88
- .from(
89
- mcp('fetch-webpage', {
90
- description: 'Fetch and return the content of a webpage',
91
- schema: z.object({
92
- url: z.string().url(),
93
- }),
94
- keywords: ['fetch', 'web', 'http'],
95
- })
96
- )
97
- .enrich(http({ url: (ex) => ex.body.url })),
98
- ])
99
- .build();
100
- await ctx.start();
140
+ ## Documentation
101
141
 
102
- // Query registered tools after context has started
103
- const registry = ctx.getStore(DirectAdapter.ADAPTER_DIRECT_REGISTRY);
104
- const tools = Array.from(registry?.values() ?? []);
105
- ```
142
+ For full guides and examples, visit [routecraft.dev](https://routecraft.dev).
106
143
 
107
144
  ## Contributing
108
145
 
109
- Contributions are welcome! Please see our [Contributing Guide](https://github.com/routecraftjs/routecraft/blob/main/CONTRIBUTING.md).
146
+ Contributions are welcome. See the [Contributing Guide](https://github.com/routecraftjs/routecraft/blob/main/CONTRIBUTING.md).
110
147
 
111
148
  ## License
112
149
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routecraft/ai",
3
- "version": "0.3.0-canary.9",
3
+ "version": "0.3.0",
4
4
  "description": "AI and MCP integrations for RouteCraft",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -23,17 +23,17 @@
23
23
  "prepublishOnly": "pnpm run build"
24
24
  },
25
25
  "dependencies": {
26
- "@routecraft/routecraft": "^0.3.0-canary.9",
26
+ "@routecraft/routecraft": "^0.4.0",
27
27
  "@standard-schema/spec": "^1.1.0",
28
- "ai": "^6.0.105"
28
+ "ai": "^6.0.116"
29
29
  },
30
30
  "devDependencies": {
31
- "@ai-sdk/anthropic": "^3.0.50",
32
- "@ai-sdk/google": "^3.0.34",
33
- "@ai-sdk/openai": "^3.0.37",
31
+ "@ai-sdk/anthropic": "^3.0.58",
32
+ "@ai-sdk/google": "^3.0.43",
33
+ "@ai-sdk/openai": "^3.0.41",
34
34
  "@huggingface/transformers": "^3.8.1",
35
35
  "@modelcontextprotocol/sdk": "^1.27.1",
36
- "@openrouter/ai-sdk-provider": "^2.2.3",
36
+ "@openrouter/ai-sdk-provider": "^2.2.5",
37
37
  "ollama-ai-provider-v2": "^3.3.1",
38
38
  "vitest": "^4.0.18",
39
39
  "zod": "^4.3.6"