@nestjs-adk/mcp 0.0.2 → 1.0.0

package/README.md

@@ -1,13 +1,59 @@
 # @nestjs-adk/mcp
 
-Consume external MCP servers as agent tools for [`@nestjs-adk/core`](https://www.npmjs.com/package/@nestjs-adk/core), via the official `@modelcontextprotocol/sdk` (stdio, streamable HTTP, SSE).
+MCP tools for [`@nestjs-adk/core`](https://www.npmjs.com/package/@nestjs-adk/core) agents.
+
+The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that exposes tools from external servers, like GitHub, filesystems or your own services. This package connects your NestJS agents to those servers. The server's catalog becomes agent tools automatically, with each JSON Schema converted to Zod.
+
+## Setup
+
+```bash
+npm i @nestjs-adk/core @nestjs-adk/mcp
+```
+
+Register the servers once:
+
+```ts
+import { McpModule } from "@nestjs-adk/mcp";
+
+@Module({
+	imports: [
+		AdkModule.forRoot({ ... }),
+		McpModule.forRoot({
+			servers: [
+				{ name: "github", transport: { type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] } },
+			],
+		}),
+	],
+})
+export class AppModule {}
+```
+
+Transports are `stdio` for local processes, `http` for streamable HTTP servers and `sse` for legacy SSE servers.
+
+## Giving the tools to an agent
+
+Use `toolset` in the agent's tool list. You can expose the whole catalog or pick specific tools:
 
 ```ts
-McpModule.forRoot({ servers: [{ name: "github", transport: { type: "stdio", command: "npx", args: [...] } }] })
+import { toolset } from "@nestjs-adk/core";
 
-@Agent({ ..., tools: [toolset("github", ["create_issue"])] }) // the server's catalog becomes tools (JSON Schema → Zod)
+@Agent({
+	name: "dev_assistant",
+	description: "Helps with repository tasks.",
+	prompt: "You help the team manage GitHub issues.",
+	tools: [toolset("github", ["create_issue", "list_issues"])],
+})
+export class DevAssistantAgent extends AdkAgent {}
 ```
 
-The catalog is cached at boot (fail-fast; `optional: true` for non-critical servers). Runtime tool failures return as `{ error }` to the LLM; connection errors become typed `McpConnectionError`s.
+Omit the second argument to expose every tool the server offers.
+
+## Behavior you can rely on
+
+The catalog is fetched once at startup and cached. If a server is down at boot the app fails fast with a typed `McpConnectionError`, unless you mark that server with `optional: true`, in which case it is skipped with a warning.
+
+At runtime, a tool call that fails on the server side does not crash the run. The error is returned to the model as `{ error }`, so the agent can react, retry or explain the problem to the user.
+
+## Learn more
 
-Full documentation: [github.com/gabrieljsilva/nestjs-adk](https://github.com/gabrieljsilva/nestjs-adk)
+The full documentation lives in [`@nestjs-adk/core`](https://www.npmjs.com/package/@nestjs-adk/core) and in the repository at [github.com/gabrieljsilva/nestjs-adk](https://github.com/gabrieljsilva/nestjs-adk).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nestjs-adk/mcp",
-	"version": "0.0.2",
+	"version": "1.0.0",
 	"description": "MCP client integration for nestjs-adk: consume external MCP servers as agent tools.",
 	"license": "MIT",
 	"sideEffects": false,
@@ -27,15 +27,24 @@
 		"@modelcontextprotocol/sdk": "^1.12.0"
 	},
 	"peerDependencies": {
-		"@nestjs-adk/core": "^0.0.2",
+		"@nestjs-adk/core": "^1.0.0",
 		"@nestjs/common": "^10.0.0 || ^11.0.0",
 		"@nestjs/core": "^10.0.0 || ^11.0.0",
 		"zod": "^3.23.0 || ^4.0.0"
 	},
 	"devDependencies": {
-		"@nestjs-adk/core": "^0.0.2"
+		"@nestjs-adk/core": "^1.0.0"
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gabrieljsilva/nestjs-adk.git",
+		"directory": "packages/mcp"
+	},
+	"homepage": "https://github.com/gabrieljsilva/nestjs-adk#readme",
+	"bugs": {
+		"url": "https://github.com/gabrieljsilva/nestjs-adk/issues"
 	}
 }