@forinda/kickjs-mcp 2.3.0 → 2.3.1

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 (5) hide show
  1. package/README.md +66 -29
  2. package/dist/index.d.mts +2 -1
  3. package/dist/index.d.mts.map +1 -1
  4. package/dist/index.mjs +1 -1
  5. package/package.json +13 -3
package/README.md CHANGED
@@ -1,25 +1,25 @@
1
1
  # @forinda/kickjs-mcp
2
2
 
3
- [Model Context Protocol](https://modelcontextprotocol.io) server adapter for KickJS. Expose `@Controller` endpoints as callable MCP tools for Claude Code, Cursor, Zed, and other MCP-aware clients — with zero duplicated schemas.
3
+ [Model Context Protocol](https://modelcontextprotocol.io) server adapter for KickJS. Expose `@Controller` endpoints as callable MCP tools for Claude Code, Claude Desktop, Cursor, Zed, and any other MCP-aware client — with zero duplicated schemas.
4
4
 
5
- ## Status
5
+ ## Features
6
6
 
7
- **v0 — skeleton.** The decorator and adapter surface exist and compile against the framework. The tool-discovery scan and MCP SDK wiring are still TODOs inside the adapter's lifecycle hooks. This package is part of Workstream 1 of the v3 AI plan and will reach v1 when:
8
-
9
- - [ ] Tool discovery scans every `@Controller` registered in the DI container
10
- - [ ] Zod body schemas are converted to JSON Schema via the shared Swagger converter
11
- - [ ] `stdio`, `sse`, and `http` transports are wired to `@modelcontextprotocol/sdk`
12
- - [ ] The `kick mcp` CLI command starts a standalone MCP server
13
- - [ ] Integration test: start a KickJS app, connect an MCP client, call a tool
14
- - [ ] Example app in `examples/mcp-server-api/`
7
+ - **Automatic tool discovery** — walks every registered controller at startup, reads route metadata, and builds the tool registry without any manual wiring.
8
+ - **Zero schema duplication** — the route's Zod `body` schema is converted to JSON Schema automatically and used as the tool's input shape.
9
+ - **Three transports** — `stdio` for local CLI clients, `http` for remote clients behind a load balancer, and `sse` for legacy long-lived connections.
10
+ - **`explicit` and `auto` exposure modes** — either opt-in via `@McpTool` or expose every route subject to `include`/`exclude` filters.
11
+ - **Internal HTTP dispatch** — tool invocations flow through the normal Express pipeline, so middleware, auth guards, validation, and logging apply identically to external callers.
12
+ - **`kick mcp` CLI** — `kick mcp start` runs your app in stdio mode; `kick mcp init` scaffolds a `.mcp.json` config for client registration.
15
13
 
16
14
  ## Install
17
15
 
18
16
  ```bash
19
- pnpm add @forinda/kickjs-mcp @modelcontextprotocol/sdk
17
+ pnpm add @forinda/kickjs-mcp
20
18
  ```
21
19
 
22
- ## Usage (planned)
20
+ `@modelcontextprotocol/sdk` is bundled as a dependency — nothing else to install.
21
+
22
+ ## Usage
23
23
 
24
24
  ```ts
25
25
  import { bootstrap } from '@forinda/kickjs'
@@ -33,8 +33,8 @@ export const app = await bootstrap({
33
33
  name: 'task-api',
34
34
  version: '1.0.0',
35
35
  description: 'Task management MCP server',
36
- mode: 'explicit', // only @McpTool-decorated methods
37
- transport: 'sse',
36
+ mode: 'explicit',
37
+ transport: 'http',
38
38
  }),
39
39
  ],
40
40
  })
@@ -51,10 +51,8 @@ import { createTaskSchema } from './dtos/create-task.dto'
51
51
  export class TaskController {
52
52
  @Post('/', { body: createTaskSchema, name: 'CreateTask' })
53
53
  @McpTool({
54
- description: 'Create a new task with title, priority, and optional assignee',
55
- examples: [
56
- { args: { title: 'Ship v3', priority: 'high' } },
57
- ],
54
+ description: 'Create a new task with title and priority',
55
+ examples: [{ args: { title: 'Ship v3', priority: 'high' } }],
58
56
  })
59
57
  create(ctx: Ctx<KickRoutes.TaskController['create']>) {
60
58
  return this.createTaskUseCase.execute(ctx.body)
@@ -62,24 +60,63 @@ export class TaskController {
62
60
  }
63
61
  ```
64
62
 
65
- The input schema of each tool is derived automatically from the route's Zod `body` schema. Add a field, and both OpenAPI (via the Swagger adapter) and MCP pick it up on the next restart — no duplicated type declarations.
63
+ Add a field to `createTaskSchema` and both OpenAPI (via the Swagger adapter) and MCP pick it up on the next restart.
66
64
 
67
65
  ## Exposure modes
68
66
 
69
- | Mode | Behavior |
70
- |------|----------|
71
- | `explicit` (default) | Only methods decorated with `@McpTool` are exposed. |
72
- | `auto` | Every route is exposed, subject to `include` / `exclude` filters. |
67
+ | Mode | Behavior |
68
+ | -------------------- | --------------------------------------------------------------------- |
69
+ | `explicit` (default) | Only methods decorated with `@McpTool` are exposed. |
70
+ | `auto` | Every route is exposed, subject to `include` / `exclude` filters. |
73
71
 
74
- Use `explicit` in production unless you've carefully reviewed every route. `auto` is convenient during development but can leak admin or internal endpoints if you forget to filter them out.
72
+ Stay on `explicit` for public-facing apps unless every route has been reviewed. `auto` is convenient for internal tools and dev environments where you control the caller.
75
73
 
76
74
  ## Transports
77
75
 
78
- | Transport | Use case |
79
- |-----------|----------|
80
- | `stdio` | CLI MCP clients (Claude Code, Cursor). Run via `kick mcp` in a separate process. |
81
- | `sse` | Mounted on the existing Express app. Default for long-running servers. |
82
- | `http` | Simpler than SSE; gives up live notifications. |
76
+ | Transport | When to use |
77
+ | --------- | --------------------------------------------------------------------- |
78
+ | `stdio` | Local CLI clients (Claude Desktop, Claude Code, Cursor) — run via `kick mcp start` |
79
+ | `http` | Remote clients, web UIs, anything behind a load balancer. Default basePath: `/_mcp` |
80
+ | `sse` | Legacy long-lived SSE connections (still supported by some clients) |
81
+
82
+ ### Stdio with Claude Desktop
83
+
84
+ ```bash
85
+ kick mcp init # writes .mcp.json
86
+ ```
87
+
88
+ Register the server in your client's config:
89
+
90
+ ```jsonc
91
+ {
92
+ "mcpServers": {
93
+ "task-api": {
94
+ "command": "kick",
95
+ "args": ["mcp", "start"],
96
+ "cwd": "/absolute/path/to/your-app"
97
+ }
98
+ }
99
+ }
100
+ ```
101
+
102
+ ## Sharing tools with `@forinda/kickjs-ai`
103
+
104
+ Stack both decorators on the same method and one implementation serves two transports — the in-process agent loop (`AiAdapter.runAgent`) and the external MCP client:
105
+
106
+ ```ts
107
+ @Post('/', { body: createTaskSchema })
108
+ @AiTool({ name: 'create_task', description: 'Create a new task', inputSchema: createTaskSchema })
109
+ @McpTool({ description: 'Create a new task' })
110
+ async create(ctx: Ctx<KickRoutes.TaskController['create']>) {
111
+ return this.createTaskUseCase.execute(ctx.body)
112
+ }
113
+ ```
114
+
115
+ ## Documentation
116
+
117
+ Full usage guide: [kickjs.dev/guide/mcp](https://forinda.github.io/kick-js/guide/mcp)
118
+
119
+ Related: [`@forinda/kickjs-ai`](../ai) is the in-process companion — providers, memory, RAG, and the agent loop that uses the same `@AiTool` / `@McpTool` methods for your own workflows.
83
120
 
84
121
  ## License
85
122
 
package/dist/index.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
 
2
+ import * as _$_forinda_kickjs0 from "@forinda/kickjs";
2
3
  import { AdapterContext, AppAdapter, Constructor } from "@forinda/kickjs";
3
4
  import { ZodTypeAny } from "zod";
4
5
 
@@ -455,7 +456,7 @@ declare function isMcpTool(target: object, method: string): boolean;
455
456
  * `MCP_TOOL_METADATA` can never shadow each other even if the package
456
457
  * is loaded more than once.
457
458
  */
458
- declare const MCP_TOOL_METADATA: any;
459
+ declare const MCP_TOOL_METADATA: _$_forinda_kickjs0.InjectionToken<McpToolOptions>;
459
460
  //#endregion
460
461
  export { MCP_TOOL_METADATA, McpAdapter, type McpAdapterOptions, type McpAuthOptions, type McpExposureMode, McpTool, type McpToolDefinition, type McpToolExample, type McpToolOptions, type McpTransport, getMcpToolMeta, isMcpTool };
461
462
  //# sourceMappingURL=index.d.mts.map
package/dist/index.d.mts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/mcp.adapter.ts","../src/decorators.ts","../src/constants.ts"],"mappings":";;;;;;;;AAaA;;;;;AAWA;;;KAXY,YAAA;;AAoBZ;;;;;;;;KATY,eAAA;;AA8BZ;;;;;;UArBiB,cAAA;EAqCM;EAnCrB,IAAA;EAqBA;EAnBA,QAAA,GAAW,KAAA,uBAA4B,OAAA;AAAA;;;;;;;;;;;;;AA4CzC;;UA3BiB,iBAAA;EA+BH;EA7BZ,IAAA;EA6BA;EA3BA,OAAA;EA6BA;EA3BA,WAAA;EA2BM;EAzBN,IAAA,GAAO,eAAA;EAyCsB;EAvC7B,SAAA,GAAY,YAAA;EAwDE;EAtDd,OAAA,GAAU,KAAA;EA4DC;EA1DX,OAAA;EA0DyB;EAxDzB,IAAA,GAAO,cAAA;EA6CP;EA3CA,QAAA;AAAA;;;;;;;UASe,cAAA;EAmEA;EAjEf,WAAA;;EAEA,IAAA,EAAM,MAAA;EA8ES;EA5Ef,MAAA;AAAA;;;;;;;;;;;;;;UAgBe,cAAA;;;;ACxCjB;ED6CE,IAAA;;;;;;;EAOA,WAAA;ECkKqB;;;;ED7JrB,WAAA,GAAc,UAAA;ECxDL;;;ED4DT,YAAA,GAAe,UAAA;EC3CP;ED6CR,QAAA,GAAW,cAAA;ECzBH;;;;;ED+BR,MAAA;AAAA;;;;;;;;;;;;;;UAgBe,iBAAA;ECgJP;ED9IR,IAAA;EC+MQ;ED7MR,WAAA;ECqRc;EDnRd,WAAA,EAAa,MAAA;ECiYL;;;;;;ED1XR,cAAA;EElIc;EFoId,YAAA,GAAe,MAAA;;EAEf,UAAA;EEtI+B;EFwI/B,SAAA;EExIgD;EF0IhD,QAAA,GAAW,cAAA;AAAA;;;;;AA5Jb;;;;;AAWA;;;;;AASA;;;;;;;;;;AAqBA;;;;;;;;;;;;;;;;;;;;cCSa,UAAA,YAAsB,UAAA;EAAA,SACxB,IAAA;EAAA,iBAEQ,OAAA;EDMT;EAAA,iBCAS,kBAAA;EDSY;EAAA,iBCHZ,KAAA;EDOL;EAAA,QCJJ,SAAA;EDIR;;;;;AAkBF;EAlBE,QCIQ,SAAA;;;;;;;;;;;UAYA,aAAA;cAEI,OAAA,EAAS,iBAAA;EDuBrB;;;;;AAsBF;;EC5BE,YAAA,CAAa,UAAA,EAAY,WAAA,EAAa,SAAA;EDkCzB;;;;;;;;ECtBb,WAAA,CAAY,IAAA,EAAM,cAAA;ED6BlB;;;;;;;;;;;;AClGF;;EAkGQ,UAAA,CAAW,GAAA,EAAK,cAAA,GAAiB,OAAA;EA1DlB;;;;;;;;;EAAA,QAiHb,oBAAA;EAzJyB;;;;;;;;;;;;;;EAAA,QA8KnB,mBAAA;EAzGd;;;;;;EAyHM,QAAA,CAAA,GAAY,OAAA;EArCV;;;;;;;EA6DR,QAAA,CAAA,YAAqB,iBAAA;EAgFb;;;;;;;;;EAAA,QAjEA,YAAA;;ACrQV;;;;;;UD2TU,iBAAA;EC3TuD;;AAajE;;;;;EAbiE,QDsUvD,aAAA;ECzTsD;;;AAKhE;;;;;;;;ACpCA;ED+BgE,QD4UtD,cAAA;;;;;;;;;;;;;;;;;;;UAqDM,YAAA;;;;;;;;;;;UAoFN,oBAAA;;;;;;;;;;;UA0BA,oBAAA;;;;;;;;;;;;UAqBA,eAAA;AAAA;;;;;;ADniBV;;;;;AAWA;;;;;AASA;;;;;;;;;;AAqBA;;;;iBEvBgB,OAAA,CAAQ,OAAA,EAAS,cAAA,GAAiB,eAAA;;;;;;;;iBAalC,cAAA,CAAe,MAAA,UAAgB,MAAA,WAAiB,cAAA;;iBAKhD,SAAA,CAAU,MAAA,UAAgB,MAAA;;;;;;;AFpC1C;;;;;AAWA;cGXa,iBAAA"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/mcp.adapter.ts","../src/decorators.ts","../src/constants.ts"],"mappings":";;;;;;;;;;AAaA;;;;;AAWA;;KAXY,YAAA;;;AAoBZ;;;;;;;KATY,eAAA;;;AA8BZ;;;;;UArBiB,cAAA;EAqCR;EAnCP,IAAA;EAmCqB;EAjCrB,QAAA,GAAW,KAAA,uBAA4B,OAAA;AAAA;;;;;;;;;;;;;;AA4CzC;UA3BiB,iBAAA;;EAEf,IAAA;EA2BA;EAzBA,OAAA;EA2BM;EAzBN,WAAA;EA2BM;EAzBN,IAAA,GAAO,eAAA;EAyCQ;EAvCf,SAAA,GAAY,YAAA;;EAEZ,OAAA,GAAU,KAAA;EA0DK;EAxDf,OAAA;EA0DyB;EAxDzB,IAAA,GAAO,cAAA;EAsCP;EApCA,QAAA;AAAA;;;;;;;UASe,cAAA;EAmDT;EAjDN,WAAA;EAiEgC;EA/DhC,IAAA,EAAM,MAAA;EAqEO;EAnEb,MAAA;AAAA;;;;;;;;;;;;;;UAgBe,cAAA;EAkEU;;;;EA7DzB,IAAA;EC7CsB;;;;;;EDoDtB,WAAA;EC0IkB;;;;EDrIlB,WAAA,GAAc,UAAA;ECzDmB;;;ED6DjC,YAAA,GAAe,UAAA;EC9CE;EDgDjB,QAAA,GAAW,cAAA;ECrCH;;;;;ED2CR,MAAA;AAAA;;;;;;;;;;;;;;UAgBe,iBAAA;ECiIM;ED/HrB,IAAA;ECoMQ;EDlMR,WAAA;ECgOQ;ED9NR,WAAA,EAAa,MAAA;ECuWL;;;;;;EDhWR,cAAA;;EAEA,YAAA,GAAe,MAAA;EEpIM;EFsIrB,UAAA;EEtI+D;EFwI/D,SAAA;EExIsB;EF0ItB,QAAA,GAAW,cAAA;AAAA;;;;;;AA5Jb;;;;;AAWA;;;;;AASA;;;;;;;;;;AAqBA;;;;;;;;;;;;;;;;;;;cCSa,UAAA,YAAsB,UAAA;EAAA,SACxB,IAAA;EAAA,iBAEQ,OAAA;EDMT;EAAA,iBCAS,kBAAA;EDSF;EAAA,iBCHE,KAAA;;UAGT,SAAA;EDER;;;;;;EAAA,QCMQ,SAAA;EDcqB;;;;;;;;;;EAAA,QCFrB,aAAA;cAEI,OAAA,EAAS,iBAAA;EDqBN;;;;;;AAwBjB;EC5BE,YAAA,CAAa,UAAA,EAAY,WAAA,EAAa,SAAA;;;;;;;;;EAYtC,WAAA,CAAY,IAAA,EAAM,cAAA;EDsBL;;;;;;;;;;;;;AC3Ff;EAkGQ,UAAA,CAAW,GAAA,EAAK,cAAA,GAAiB,OAAA;;;;;;;;;;UAuD/B,oBAAA;EAzJmC;;;;;;;;;;;;;;EAAA,QA8K7B,mBAAA;EArHwB;;;;;;EAqIhC,QAAA,CAAA,GAAY,OAAA;EA5FqB;;;;;;;EAoHvC,QAAA,CAAA,YAAqB,iBAAA;EAqEb;;;;;;;;;EAAA,QAtDA,YAAA;;;ACrQV;;;;;UD2TU,iBAAA;EC3TwC;;;AAalD;;;;EAbkD,QDsUxC,aAAA;ECzTqC;;;;AAK/C;;;;;;;;EAL+C,QD4UrC,cAAA;EE3WqE;;;;;;;;;;;;;;;;;;EAAA,QFga/D,YAAA;;;;;;;;;;;UAoFN,oBAAA;;;;;;;;;;;UA0BA,oBAAA;;;;;;;;;;;;UAqBA,eAAA;AAAA;;;;;;;ADniBV;;;;;AAWA;;;;;AASA;;;;;;;;;;AAqBA;;;iBEvBgB,OAAA,CAAQ,OAAA,EAAS,cAAA,GAAiB,eAAA;;;;;;;;iBAalC,cAAA,CAAe,MAAA,UAAgB,MAAA,WAAiB,cAAA;;iBAKhD,SAAA,CAAU,MAAA,UAAgB,MAAA;;;;;;;AFpC1C;;;;;AAWA;cGXa,iBAAA,EAAiB,kBAAA,CAAA,cAAA,CAAA,cAAA"}
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @forinda/kickjs-mcp v2.3.0
2
+ * @forinda/kickjs-mcp v2.3.1
3
3
  *
4
4
  * Copyright (c) Felix Orinda
5
5
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forinda/kickjs-mcp",
3
- "version": "2.3.0",
3
+ "version": "2.3.1",
4
4
  "description": "Model Context Protocol server adapter for KickJS — expose @Controller endpoints as MCP tools",
5
5
  "keywords": [
6
6
  "kickjs",
@@ -20,9 +20,19 @@
20
20
  "tool-calling",
21
21
  "agent",
22
22
  "llm",
23
+ "claude-code",
24
+ "cursor",
25
+ "zed",
26
+ "stdio",
27
+ "openapi",
23
28
  "@forinda/kickjs",
29
+ "@forinda/kickjs-mcp",
30
+ "@forinda/kickjs-ai",
24
31
  "@forinda/kickjs-cli",
25
- "@forinda/kickjs-swagger"
32
+ "@forinda/kickjs-config",
33
+ "@forinda/kickjs-swagger",
34
+ "@forinda/kickjs-auth",
35
+ "@forinda/kickjs-testing"
26
36
  ],
27
37
  "type": "module",
28
38
  "main": "dist/index.mjs",
@@ -55,7 +65,7 @@
55
65
  },
56
66
  "dependencies": {
57
67
  "reflect-metadata": "^0.2.2",
58
- "@forinda/kickjs": "2.3.0"
68
+ "@forinda/kickjs": "2.3.1"
59
69
  },
60
70
  "peerDependencies": {
61
71
  "@modelcontextprotocol/sdk": "^1.0.0",