opencode-skills-collection 4.0.52 → 4.0.54

package/bundled-skills/mcp-builder/reference/node_mcp_server.md

@@ -1,8 +1,14 @@
 # Node/TypeScript MCP Server Implementation Guide
 
+Modified in AAS on 2026-09-05. These are SDK **v1** integration sketches, with imports
+from `@modelcontextprotocol/sdk`. Confirm the installed version and lockfile against
+[the v1 guide](https://ts.sdk.modelcontextprotocol.io/server). The newer split-package
+SDK uses different imports; do not mix its examples with this guide. Service-specific
+adapters, authentication and schemas below must be supplied and tested.
+
 ## Overview
 
-This document provides Node/TypeScript-specific best practices and examples for implementing MCP servers using the MCP TypeScript SDK. It covers project structure, server setup, tool registration patterns, input validation with Zod, error handling, and complete working examples.
+This document provides Node/TypeScript-specific best practices and examples for implementing MCP servers using the MCP TypeScript SDK. It covers project structure, server setup, tool registration patterns, input validation with Zod, error handling, and version-scoped integration sketches.
 
 ---
 
@@ -55,9 +61,9 @@ The official MCP TypeScript SDK provides:
 - Zod schema integration for runtime input validation
 - Type-safe tool handler implementations
 
-**IMPORTANT - Use Modern APIs Only:**
+**Choose the API supported by the installed SDK:**
 - **DO use**: `server.registerTool()`, `server.registerResource()`, `server.registerPrompt()`
-- **DO NOT use**: Old deprecated APIs such as `server.tool()`, `server.setRequestHandler(ListToolsRequestSchema, ...)`, or manual handler registration
+- Low-level `Server.setRequestHandler` remains useful for explicit protocol contracts; do not label it deprecated merely because a high-level wrapper exists
 - The `register*` methods provide better type safety, automatic schema handling, and are the recommended approach
 
 See the MCP SDK documentation in the references for complete details.
@@ -263,6 +269,7 @@ Error Handling:
       };
     } catch (error) {
       return {
+        isError: true,
         content: [{
           type: "text",
           text: handleApiError(error)
@@ -348,7 +355,7 @@ const inputSchema = z.object({
 
 **JSON format**:
 - Return complete, structured data suitable for programmatic processing
-- Include all available fields and metadata
+- Include authorized fields needed by this task
 - Use consistent field names and types
 
 ## Pagination Implementation
@@ -379,31 +386,13 @@ async function listItems(params: z.infer<typeof ListSchema>) {
 }
 ```
 
-## Character Limits and Truncation
-
-Add a CHARACTER_LIMIT constant to prevent overwhelming responses:
-
-```typescript
-// At module level in constants.ts
-export const CHARACTER_LIMIT = 25000;  // Maximum response size in characters
-
-async function searchTool(params: SearchInput) {
-  let result = generateResponse(data);
-
-  // Check character limit and truncate if needed
-  if (result.length > CHARACTER_LIMIT) {
-    const truncatedData = data.slice(0, Math.max(1, data.length / 2));
-    response.data = truncatedData;
-    response.truncated = true;
-    response.truncation_message =
-      `Response truncated from ${data.length} to ${truncatedData.length} items. ` +
-      `Use 'offset' parameter or add filters to see more results.`;
-    result = JSON.stringify(response, null, 2);
-  }
+## Bounded response serialization
 
-  return result;
-}
-```
+Limit upstream response bytes and result counts before parsing. Reduce whole items,
+then serialize and check actual UTF-8 bytes, including metadata and text duplication.
+If one item cannot fit, return an explicit tool error with narrower-query guidance.
+Never slice serialized JSON or halve once and assume the result fits. Preserve a
+cursor for omitted results and distinguish truncation from an empty successful page.
 
 ## Error Handling
 
@@ -429,7 +418,7 @@ function handleApiError(error: unknown): string {
       return "Error: Request timed out. Please try again.";
     }
   }
-  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
+  return "Error: Unexpected upstream failure; consult the restricted server log.";
 }
 ```
 
@@ -541,10 +530,10 @@ async function getUser(id: string): Promise<any> {
     "clean": "rm -rf dist"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@modelcontextprotocol/sdk": "^1.10.0",
     "axios": "^1.7.9",
     "zod": "^3.23.8"
   },
@@ -581,7 +570,7 @@ async function getUser(id: string): Promise<any> {
 }
 ```
 
-## Complete Example
+## Integration outline (not a runnable complete service)
 
 ```typescript
 #!/usr/bin/env node
@@ -673,7 +662,7 @@ function handleApiError(error: unknown): string {
       return "Error: Request timed out. Please try again.";
     }
   }
-  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
+  return "Error: Unexpected upstream failure; consult the restricted server log.";
 }
 
 // Create MCP server instance
@@ -714,45 +703,10 @@ async function runStdio() {
   console.error("MCP server running via stdio");
 }
 
-// For streamable HTTP (remote):
-async function runHTTP() {
-  if (!process.env.EXAMPLE_API_KEY) {
-    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
-    process.exit(1);
-  }
-
-  const app = express();
-  app.use(express.json());
-
-  app.post('/mcp', async (req, res) => {
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: undefined,
-      enableJsonResponse: true
-    });
-    res.on('close', () => transport.close());
-    await server.connect(transport);
-    await transport.handleRequest(req, res, req.body);
-  });
-
-  const port = parseInt(process.env.PORT || '3000');
-  app.listen(port, () => {
-    console.error(`MCP server running on http://localhost:${port}/mcp`);
-  });
-}
-
-// Choose transport based on environment
-const transport = process.env.TRANSPORT || 'stdio';
-if (transport === 'http') {
-  runHTTP().catch(error => {
-    console.error("Server error:", error);
-    process.exit(1);
-  });
-} else {
-  runStdio().catch(error => {
-    console.error("Server error:", error);
-    process.exit(1);
-  });
-}
+runStdio().catch(() => {
+  console.error("Server startup failed");
+  process.exitCode = 1;
+});
 ```
 
 ---
@@ -764,50 +718,23 @@ if (transport === 'http') {
 Expose data as resources for efficient, URI-based access:
 
 ```typescript
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
-// Register a resource with URI template
+// Static allowlist, not a filesystem path derived from user input.
+const documents = new Map([["help", "Synthetic fixture documentation"]]);
 server.registerResource(
-  {
-    uri: "file://documents/{name}",
-    name: "Document Resource",
-    description: "Access documents by name",
-    mimeType: "text/plain"
-  },
-  async (uri: string) => {
-    // Extract parameter from URI
-    const match = uri.match(/^file:\/\/documents\/(.+)$/);
-    if (!match) {
-      throw new Error("Invalid URI format");
-    }
-
-    const documentName = match[1];
-    const content = await loadDocument(documentName);
-
-    return {
-      contents: [{
-        uri,
-        mimeType: "text/plain",
-        text: content
-      }]
-    };
+  "document", new ResourceTemplate("docs://{name}", { list: undefined }),
+  { mimeType: "text/plain" },
+  async (uri, { name }) => {
+    if (typeof name !== "string" || !documents.has(name)) throw new Error("Unknown document");
+    return { contents: [{ uri: uri.href, text: documents.get(name)! }] };
   }
 );
-
-// List available resources dynamically
-server.registerResourceList(async () => {
-  const documents = await getAvailableDocuments();
-  return {
-    resources: documents.map(doc => ({
-      uri: `file://documents/${doc.name}`,
-      name: doc.name,
-      mimeType: "text/plain",
-      description: doc.description
-    }))
-  };
-});
 ```
 
+Real resources need per-principal authorization, bounded reads and safe path handling;
+a template match alone grants no filesystem access.
+
 **When to use Resources vs Tools:**
 - **Resources**: For data access with simple URI-based parameters
 - **Tools**: For complex operations requiring validation and business logic
@@ -820,28 +747,11 @@ The TypeScript SDK supports two main transport mechanisms:
 
 #### Streamable HTTP (Recommended for Remote Servers)
 
-```typescript
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import express from "express";
-
-const app = express();
-app.use(express.json());
-
-app.post('/mcp', async (req, res) => {
-  // Create new transport for each request (stateless, prevents request ID collisions)
-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: undefined,
-    enableJsonResponse: true
-  });
-
-  res.on('close', () => transport.close());
-
-  await server.connect(transport);
-  await transport.handleRequest(req, res, req.body);
-});
-
-app.listen(3000);
-```
+Use the installed SDK's tested HTTP example. For stateless handling, create both a
+server and transport for each request; sharing a connected server across concurrent
+transports is not a session model. Enforce authentication, token audience/scopes,
+origin/host validation, request limits and cleanup before exposing the endpoint.
+A localhost demonstration without these controls is not a deployment template.
 
 #### stdio (For Local Integrations)
 
@@ -860,17 +770,9 @@ await server.connect(transport);
 
 Notify clients when server state changes:
 
-```typescript
-// Notify when tools list changes
-server.notification({
-  method: "notifications/tools/list_changed"
-});
-
-// Notify when resources change
-server.notification({
-  method: "notifications/resources/list_changed"
-});
-```
+Use the installed SDK's notification API and the negotiated client's capabilities.
+Do not call an invented high-level `server.notification` method. Verify receipt in a
+real client; protocol versions and session models differ.
 
 Use notifications sparingly - only when server capabilities genuinely change.
 
@@ -965,6 +867,6 @@ Before finalizing your Node/TypeScript MCP server implementation, ensure:
 ### Testing and Build
 - [ ] `npm run build` completes successfully without errors
 - [ ] dist/index.js created and executable
-- [ ] Server runs: `node dist/index.js --help`
+- [ ] Real client initializes the built stdio command and invokes a fixture tool; do not assume --help exists
 - [ ] All imports resolve correctly
 - [ ] Sample tool calls work as expected

package/bundled-skills/mcp-builder/reference/python_mcp_server.md

@@ -1,8 +1,13 @@
 # Python MCP Server Implementation Guide
 
+Modified in AAS on 2026-09-05. These examples target MCP Python SDK v1 and Pydantic v2.
+Check the installed versions against their matching documentation. They are integration
+sketches: example.com is a placeholder, authentication and application adapters must be
+provided, and syntax compilation does not prove protocol/client compatibility.
+
 ## Overview
 
-This document provides Python-specific best practices and examples for implementing MCP servers using the MCP Python SDK. It covers server setup, tool registration patterns, input validation with Pydantic, error handling, and complete working examples.
+This document provides Python-specific best practices and examples for implementing MCP servers using the MCP Python SDK. It covers server setup, tool registration patterns, input validation with Pydantic, error handling, and integration sketches.
 
 ---
 
@@ -87,7 +92,7 @@ class ServiceToolInput(BaseModel):
 
     param1: str = Field(..., description="First parameter description (e.g., 'user123', 'project-abc')", min_length=1, max_length=100)
     param2: Optional[int] = Field(default=None, description="Optional integer parameter with constraints", ge=0, le=1000)
-    tags: Optional[List[str]] = Field(default_factory=list, description="List of tags to apply", max_items=10)
+    tags: Optional[List[str]] = Field(default_factory=list, description="List of tags to apply", max_length=10)
 
 @mcp.tool(
     name="service_tool_name",
@@ -132,7 +137,8 @@ from pydantic import BaseModel, Field, field_validator, ConfigDict
 class CreateUserInput(BaseModel):
     model_config = ConfigDict(
         str_strip_whitespace=True,
-        validate_assignment=True
+        validate_assignment=True,
+        extra="forbid"
     )
 
     name: str = Field(..., description="User's full name", min_length=1, max_length=100)
@@ -176,7 +182,7 @@ class UserSearchInput(BaseModel):
 
 **JSON format**:
 - Return complete, structured data suitable for programmatic processing
-- Include all available fields and metadata
+- Include only the authorized fields required by the task
 - Use consistent field names and types
 
 ## Pagination Implementation
@@ -185,8 +191,8 @@ For tools that list resources:
 
 ```python
 class ListInput(BaseModel):
-    limit: Optional[int] = Field(default=20, description="Maximum results to return", ge=1, le=100)
-    offset: Optional[int] = Field(default=0, description="Number of results to skip for pagination", ge=0)
+    limit: int = Field(default=20, description="Maximum results to return", ge=1, le=100)
+    offset: int = Field(default=0, description="Number of results to skip for pagination", ge=0)
 
 async def list_items(params: ListInput) -> str:
     # Make API request with pagination
@@ -327,9 +333,9 @@ async def search_users(params: UserSearchInput) -> str:
     '''
 ```
 
-## Complete Example
+## Integration example (requires a real service adapter)
 
-See below for a complete Python MCP server example:
+The following skeleton needs service-specific authorization and response validation:
 
 ```python
 #!/usr/bin/env python3
@@ -363,12 +369,13 @@ class UserSearchInput(BaseModel):
     '''Input model for user search operations.'''
     model_config = ConfigDict(
         str_strip_whitespace=True,
-        validate_assignment=True
+        validate_assignment=True,
+        extra="forbid"
     )
 
     query: str = Field(..., description="Search string to match against names/emails", min_length=2, max_length=200)
-    limit: Optional[int] = Field(default=20, description="Maximum results to return", ge=1, le=100)
-    offset: Optional[int] = Field(default=0, description="Number of results to skip for pagination", ge=0)
+    limit: int = Field(default=20, description="Maximum results to return", ge=1, le=100)
+    offset: int = Field(default=0, description="Number of results to skip for pagination", ge=0)
     response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="Output format")
 
     @field_validator('query')
@@ -465,7 +472,7 @@ async def example_search_users(params: UserSearchInput) -> str:
             return json.dumps(response, indent=2)
 
     except Exception as e:
-        return _handle_api_error(e)
+        raise ValueError(_handle_api_error(e)) from None
 
 if __name__ == "__main__":
     mcp.run()
@@ -479,74 +486,29 @@ if __name__ == "__main__":
 
 FastMCP can automatically inject a `Context` parameter into tools for advanced capabilities like logging, progress reporting, resource reading, and user interaction:
 
-```python
-from mcp.server.fastmcp import FastMCP, Context
-
-mcp = FastMCP("example_mcp")
-
-@mcp.tool()
-async def advanced_search(query: str, ctx: Context) -> str:
-    '''Advanced tool with context access for logging and progress.'''
-
-    # Report progress for long operations
-    await ctx.report_progress(0.25, "Starting search...")
-
-    # Log information for debugging
-    await ctx.log_info("Processing query", {"query": query, "timestamp": datetime.now()})
-
-    # Perform search
-    results = await search_api(query)
-    await ctx.report_progress(0.75, "Formatting results...")
-
-    # Access server configuration
-    server_name = ctx.fastmcp.name
-
-    return format_results(results)
-
-@mcp.tool()
-async def interactive_tool(resource_id: str, ctx: Context) -> str:
-    '''Tool that can request additional input from users.'''
-
-    # Request sensitive information when needed
-    api_key = await ctx.elicit(
-        prompt="Please provide your API key:",
-        input_type="password"
-    )
-
-    # Use the provided key
-    return await api_call(resource_id, api_key)
-```
-
-**Context capabilities:**
-- `ctx.report_progress(progress, message)` - Report progress for long operations
-- `ctx.log_info(message, data)` / `ctx.log_error()` / `ctx.log_debug()` - Logging
-- `ctx.elicit(prompt, input_type)` - Request input from users
-- `ctx.fastmcp.name` - Access server configuration
-- `ctx.read_resource(uri)` - Read MCP resources
+Read the installed SDK's Context API before using progress, logging or elicitation.
+For SDK v1, use named arguments such as `progress`, `total` and `message` as supported
+by that version. Do not put queries, credentials or raw payloads in telemetry. Form
+elicitation must not request API keys or passwords; use the approved authentication
+flow. Check the client's negotiated capabilities before any request to the client.
 
 ### Resource Registration
 
 Expose data as resources for efficient, template-based access:
 
 ```python
-@mcp.resource("file://documents/{name}")
-async def get_document(name: str) -> str:
-    '''Expose documents as MCP resources.
+DOCUMENTS = {"help": "Synthetic fixture documentation"}
 
-    Resources are useful for static or semi-static data that doesn't
-    require complex parameters. They use URI templates for flexible access.
-    '''
-    document_path = f"./docs/{name}"
-    with open(document_path, "r") as f:
-        return f.read()
-
-@mcp.resource("config://settings/{key}")
-async def get_setting(key: str, ctx: Context) -> str:
-    '''Expose configuration as resources with context.'''
-    settings = await load_settings()
-    return json.dumps(settings.get(key, {}))
+@mcp.resource("docs://{name}")
+def get_document(name: str) -> str:
+    if name not in DOCUMENTS:
+        raise ValueError("Unknown document")
+    return DOCUMENTS[name]
 ```
 
+A real resource needs per-principal authorization and bounded reads. Never concatenate
+a template parameter into a filesystem path or expose arbitrary configuration keys.
+
 **When to use Resources vs Tools:**
 - **Resources**: For data access with simple parameters (URI templates)
 - **Tools**: For complex operations with validation and business logic
@@ -594,24 +556,24 @@ Initialize resources that persist across requests:
 from contextlib import asynccontextmanager
 
 @asynccontextmanager
-async def app_lifespan():
+async def app_lifespan(server: FastMCP):
     '''Manage resources that live for the server's lifetime.'''
     # Initialize connections, load config, etc.
     db = await connect_to_database()
     config = load_configuration()
 
     # Make available to all tools
-    yield {"db": db, "config": config}
-
-    # Cleanup on shutdown
-    await db.close()
+    try:
+        yield {"db": db, "config": config}
+    finally:
+        await db.close()
 
 mcp = FastMCP("example_mcp", lifespan=app_lifespan)
 
 @mcp.tool()
 async def query_data(query: str, ctx: Context) -> str:
     '''Access lifespan resources through context.'''
-    db = ctx.request_context.lifespan_state["db"]
+    db = ctx.request_context.lifespan_context["db"]
     results = await db.query(query)
     return format_results(results)
 ```
@@ -627,7 +589,7 @@ if __name__ == "__main__":
 
 # Streamable HTTP transport (for remote servers)
 if __name__ == "__main__":
-    mcp.run(transport="streamable_http", port=8000)
+    mcp.run(transport="streamable-http")  # Configure host/port on FastMCP for the installed SDK
 ```
 
 **Transport selection:**
@@ -694,7 +656,7 @@ Before finalizing your Python MCP server implementation, ensure:
 - [ ] All Pydantic Fields have explicit types and descriptions with constraints
 - [ ] All tools have comprehensive docstrings with explicit input/output types
 - [ ] Docstrings include complete schema structure for dict/JSON returns
-- [ ] Pydantic models handle input validation (no manual validation needed)
+- [ ] Pydantic validates structure; authorization and application invariants are checked separately
 
 ### Advanced Features (where applicable)
 - [ ] Context injection used for logging, progress, or elicitation
@@ -713,7 +675,7 @@ Before finalizing your Python MCP server implementation, ensure:
 - [ ] Constants are defined at module level in UPPER_CASE
 
 ### Testing
-- [ ] Server runs successfully: `python your_server.py --help`
+- [ ] Real client initializes the stdio command and invokes a fixture tool; --help may not be implemented
 - [ ] All imports resolve correctly
 - [ ] Sample tool calls work as expected
 - [ ] Error scenarios handled gracefully

package/bundled-skills/mcp-builder/scripts/connections.py

@@ -35,7 +35,7 @@ class MCPConnection(ABC):
             elif len(result) == 3:
                 read, write, _ = result
             else:
-                raise ValueError(f"Unexpected context result: {result}")
+                raise ValueError("Unexpected connection context shape")
 
             session_ctx = ClientSession(read, write)
             self.session = await self._stack.enter_async_context(session_ctx)
@@ -54,20 +54,27 @@ class MCPConnection(ABC):
 
     async def list_tools(self) -> list[dict[str, Any]]:
         """Retrieve available tools from the MCP server."""
-        response = await self.session.list_tools()
-        return [
-            {
-                "name": tool.name,
-                "description": tool.description,
-                "input_schema": tool.inputSchema,
-            }
-            for tool in response.tools
-        ]
+        tools = []
+        seen_cursors = set()
+        cursor = None
+        for _ in range(100):
+            response = await self.session.list_tools(cursor=cursor)
+            tools.extend({"name": tool.name, "description": tool.description or "",
+                          "input_schema": tool.inputSchema} for tool in response.tools)
+            if len(tools) > 1000 or len({tool["name"] for tool in tools}) != len(tools):
+                raise ValueError("Oversized or duplicate tool inventory")
+            cursor = response.nextCursor
+            if not cursor:
+                return tools
+            if cursor in seen_cursors:
+                raise ValueError("Repeated tool-list cursor")
+            seen_cursors.add(cursor)
+        raise ValueError("Tool-list page budget exhausted")
 
     async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
         """Call a tool on the MCP server with provided arguments."""
         result = await self.session.call_tool(tool_name, arguments=arguments)
-        return result.content
+        return result.model_dump(mode="json", by_alias=True, exclude_none=True)
 
 
 class MCPConnectionStdio(MCPConnection):