workspace-architect 1.3.0

package/assets/instructions/terraform-sap-btp.instructions.md

@@ -0,0 +1,195 @@
+---
+description: 'Terraform conventions and guidelines for SAP Business Technology Platform (SAP BTP).'
+applyTo: '**/*.tf, **/*.tfvars, **/*.tflint.hcl, **/*.tf.json, **/*.tfvars.json'
+---
+
+# Terraform on SAP BTP – Best Practices & Conventions
+
+## Core Principles
+
+Keep Terraform code minimal, modular, repeatable, secure, and auditable.
+Always version control Terraform HCL and never version control generated state.
+
+## Security
+
+Mandatory:
+- Use the latest stable Terraform CLI and provider versions; upgrade proactively for security patches.
+- Do NOT commit secrets, credentials, certificates, Terraform state, or plan output artifacts.
+- Mark all secret variables and outputs as `sensitive = true`.
+- Prefer ephemeral / write‑only provider auth (Terraform >= 1.11) so secrets never persist in state.
+- Minimize sensitive outputs; emit only what downstream automation truly needs.
+- Continuously scan with `tfsec`, `trivy`, `checkov` (pick at least one) in CI.
+- Periodically review provider credentials, rotate keys, and enable MFA where supported.
+
+## Modularity
+
+Structure for clarity and speed:
+- Split by logical domain (e.g., entitlements, service instances) – NOT by environment.
+- Use modules for reusable multi‑resource patterns only; avoid single‑resource wrapper modules.
+- Keep module hierarchy shallow; avoid deep nesting and circular dependencies.
+- Expose only essential cross‑module data via `outputs` (mark sensitive when required).
+
+## Maintainability
+
+Aim for explicit > implicit.
+- Comment WHY, not WHAT; avoid restating obvious resource attributes.
+- Parameterize (variables) instead of hard‑coding; provide defaults only when sensible.
+- Prefer data sources for external existing infra; never for resources just created in same root – use outputs.
+- Avoid data sources in generic reusable modules; require inputs instead.
+- Remove unused / slow data sources; they degrade plan time.
+- Use `locals` for derived or repeated expressions to centralize logic.
+
+## Style & Formatting
+
+### General
+- Descriptive, consistent names for resources, variables, outputs.
+- snake_case for variables & locals.
+- 2 spaces indentation; run `terraform fmt -recursive`.
+
+### Layout & Files
+
+Recommended structure:
+```text
+my-sap-btp-app/
+├── infra/                      # Root module
+│   ├── main.tf                 # Core resources (split by domain when large)
+│   ├── variables.tf            # Inputs
+│   ├── outputs.tf              # Outputs
+│   ├── provider.tf             # Provider config(s)
+│   ├── locals.tf               # Local/derived values
+│   └── environments/           # Environment var files only
+│       ├── dev.tfvars
+│       ├── test.tfvars
+│       └── prod.tfvars
+├── .github/workflows/          # CI/CD (if GitHub)
+└── README.md                   # Documentation
+```
+
+Rules:
+- Do NOT create separate branches/repos/folders per environment (antipattern).
+- Keep environment drift minimal; encode differences in *.tfvars files only.
+- Split oversized `main.tf` / `variables.tf` into logically named fragments (e.g., `main_services.tf`, `variables_services.tf`).
+  Keep naming consistent.
+
+### Resource Block Organization
+
+Order (top → bottom): optional `depends_on`, then `count`/`for_each`, then attributes, finally `lifecycle`.
+- Use `depends_on` ONLY when Terraform cannot infer dependency (e.g., data source needs entitlement).
+- Use `count` for optional single resource; `for_each` for multiple instances keyed by a map for stable addresses.
+- Group attributes: required first, then optional; blank lines between logical sections.
+- Alphabetize within a section for faster scanning.
+
+### Variables
+- Every variable: explicit `type`, non‑empty `description`.
+- Prefer concrete types (`object`, `map(string)`, etc.) over `any`.
+- Avoid null defaults for collections; use empty lists/maps instead.
+
+### Locals
+- Centralize computed or repeated expressions.
+- Group related values into object locals for cohesion.
+
+### Outputs
+- Expose only what downstream modules/automation consume.
+- Mark secrets `sensitive = true`.
+- Always give a clear `description`.
+
+### Formatting & Linting
+- Run `terraform fmt -recursive` (required in CI).
+- Enforce `tflint` (and optionally `terraform validate`) in pre‑commit / CI.
+
+## Documentation
+
+Mandatory:
+- `description` + `type` on all variables & outputs.
+- A concise root `README.md`: purpose, prerequisites, auth model, usage (init/plan/apply), testing, rollback.
+- Generate module docs with `terraform-docs` (add to CI if possible).
+- Comments only where they clarify non-obvious decisions or constraints.
+
+## State Management
+- Use a remote backend supporting locking (e.g., Terraform Cloud, AWS S3, GCS, Azure Storage). Avoid SAP BTP Object Store (insufficient capabilities for reliable locking & security).
+- NEVER commit `*.tfstate` or backups.
+- Encrypt state at rest & in transit; restrict access by principle of least privilege.
+
+## Validation
+- Run `terraform validate` (syntax & internal checks) before committing.
+- Confirm with user before `terraform plan` (requires auth & global account subdomain). Provide auth via env vars or tfvars; NEVER inline secrets in provider blocks.
+- Test in non‑prod first; ensure idempotent applies.
+
+## Testing
+- Use Terraform test framework (`*.tftest.hcl`) for module logic & invariants.
+- Cover success & failure paths; keep tests stateless/idempotent.
+- Prefer mocking external data sources where feasible.
+
+## SAP BTP Provider Specifics
+
+Guidelines:
+- Resolve service plan IDs using `data "btp_subaccount_service_plan"` and reference `serviceplan_id` from that data source.
+
+Example:
+```terraform
+data "btp_subaccount_service_plan" "example" {
+  subaccount_id = var.subaccount_id
+  service_name  = "your_service_name"
+  plan_name     = "your_plan_name"
+}
+
+resource "btp_subaccount_service_instance" "example" {
+  subaccount_id  = var.subaccount_id
+  serviceplan_id = data.btp_subaccount_service_plan.example.id
+  name           = "my-example-instance"
+}
+```
+
+Explicit dependencies (provider cannot infer):
+```terraform
+resource "btp_subaccount_entitlement" "example" {
+  subaccount_id = var.subaccount_id
+  service_name  = "your_service_name"
+  plan_name     = "your_plan_name"
+}
+
+data "btp_subaccount_service_plan" "example" {
+  subaccount_id = var.subaccount_id
+  service_name  = "your_service_name"
+  plan_name     = "your_plan_name"
+  depends_on    = [btp_subaccount_entitlement.example]
+}
+```
+
+Subscriptions also depend on entitlements; add `depends_on` when the provider cannot infer linkage via attributes (match `service_name`/`plan_name` ↔ `app_name`).
+
+## Tool Integration
+
+### HashiCorp Terraform MCP Server
+Use the Terraform MCP Server for interactive schema lookup, resource block drafting, and validation.
+1. Install & run server (see https://github.com/mcp/hashicorp/terraform-mcp-server).
+2. Add it as a tool in your Copilot / MCP client configuration.
+3. Query provider schema (e.g., list resources, data sources) before authoring.
+4. Generate draft resource blocks, then refine manually for naming & tagging standards.
+5. Validate plan summaries (never include secrets); confirm diff with reviewer before `apply`.
+
+### Terraform Registry
+Reference the SAP BTP provider docs: https://registry.terraform.io/providers/SAP/btp/latest/docs for authoritative resource & data source fields. Cross‑check MCP responses with registry docs if uncertain.
+
+## Anti‑Patterns (Avoid)
+
+Configuration:
+- Hard‑coded environment‑specific values (use variables & tfvars).
+- Routine use of `terraform import` (migration only).
+- Deep / opaque conditional logic and dynamic blocks that reduce clarity.
+- `local-exec` provisioners except for unavoidable integration gaps.
+- Mixing SAP BTP provider with Cloud Foundry provider in the same root unless explicitly justified (split modules).
+
+Security:
+- Storing secrets in HCL, state, or VCS.
+- Disabling encryption, validation, or scanning for speed.
+- Using default passwords/keys or reusing credentials across environments.
+
+Operational:
+- Direct production applies without prior non‑prod validation.
+- Manual drift changes outside Terraform.
+- Ignoring state inconsistencies / corruption symptoms.
+- Running production applies from uncontrolled local laptops (use CI/CD or approved runners).
+- Reading business data from raw `*.tfstate` instead of outputs / data sources.
+
+All changes must flow through Terraform CLI + HCL – never mutate state manually.

package/assets/instructions/terraform.instructions.md

@@ -0,0 +1,113 @@
+---
+description: 'Terraform Conventions and Guidelines'
+applyTo: '**/*.tf'
+---
+
+# Terraform Conventions
+
+## General Instructions
+
+- Use Terraform to provision and manage infrastructure.
+- Use version control for your Terraform configurations.
+
+## Security
+
+- Always use the latest stable version of Terraform and its providers.
+  - Regularly update your Terraform configurations to incorporate security patches and improvements.
+- Store sensitive information in a secure manner, such as using AWS Secrets Manager or SSM Parameter Store.
+  - Regularly rotate credentials and secrets.
+  - Automate the rotation of secrets, where possible.
+- Use AWS environment variables to reference values stored in AWS Secrets Manager or SSM Parameter Store.
+  - This keeps sensitive values out of your Terraform state files.
+- Never commit sensitive information such as AWS credentials, API keys, passwords, certificates, or Terraform state to version control.
+  - Use `.gitignore` to exclude files containing sensitive information from version control.
+- Always mark sensitive variables as `sensitive = true` in your Terraform configurations.
+  - This prevents sensitive values from being displayed in the Terraform plan or apply output.
+- Use IAM roles and policies to control access to resources.
+  - Follow the principle of least privilege when assigning permissions.
+- Use security groups and network ACLs to control network access to resources.
+- Deploy resources in private subnets whenever possible.
+  - Use public subnets only for resources that require direct internet access, such as load balancers or NAT gateways.
+- Use encryption for sensitive data at rest and in transit.
+  - Enable encryption for EBS volumes, S3 buckets, and RDS instances.
+  - Use TLS for communication between services.
+- Regularly review and audit your Terraform configurations for security vulnerabilities.
+  - Use tools like `trivy`, `tfsec`, or `checkov` to scan your Terraform configurations for security issues.
+
+## Modularity
+
+- Use separate projects for each major component of the infrastructure; this:
+  - Reduces complexity
+  - Makes it easier to manage and maintain configurations
+  - Speeds up `plan` and `apply` operations
+  - Allows for independent development and deployment of components
+  - Reduces the risk of accidental changes to unrelated resources
+- Use modules to avoid duplication of configurations.
+  - Use modules to encapsulate related resources and configurations.
+  - Use modules to simplify complex configurations and improve readability.
+  - Avoid circular dependencies between modules.
+  - Avoid unnecessary layers of abstraction; use modules only when they add value.
+    - Avoid using modules for single resources; only use them for groups of related resources.
+    - Avoid excessive nesting of modules; keep the module hierarchy shallow.
+- Use `output` blocks to expose important information about your infrastructure.
+  - Use outputs to provide information that is useful for other modules or for users of the configuration.
+  - Avoid exposing sensitive information in outputs; mark outputs as `sensitive = true` if they contain sensitive data.
+
+## Maintainability
+
+- Prioritize readability, clarity, and maintainability.
+- Use comments to explain complex configurations and why certain design decisions were made.
+- Write concise, efficient, and idiomatic configs that are easy to understand.
+- Avoid using hard-coded values; use variables for configuration instead.
+  - Set default values for variables, where appropriate.
+- Use data sources to retrieve information about existing resources instead of requiring manual configuration.
+  - This reduces the risk of errors, ensures that configurations are always up-to-date, and allows configurations to adapt to different environments.
+  - Avoid using data sources for resources that are created within the same configuration; use outputs instead.
+  - Avoid, or remove, unnecessary data sources; they slow down `plan` and `apply` operations.
+- Use `locals` for values that are used multiple times to ensure consistency.
+
+## Style and Formatting
+
+- Follow Terraform best practices for resource naming and organization.
+  - Use descriptive names for resources, variables, and outputs.
+  - Use consistent naming conventions across all configurations.
+- Follow the **Terraform Style Guide** for formatting.
+  - Use consistent indentation (2 spaces for each level).
+- Group related resources together in the same file.
+  - Use a consistent naming convention for resource groups (e.g., `providers.tf`, `variables.tf`, `network.tf`, `ecs.tf`, `mariadb.tf`).
+- Place `depends_on` blocks at the very beginning of resource definitions to make dependency relationships clear.
+  - Use `depends_on` only when necessary to avoid circular dependencies.
+- Place `for_each` and `count` blocks at the beginning of resource definitions to clarify the resource's instantiation logic.
+  - Use `for_each` for collections and `count` for numeric iterations.
+  - Place them after `depends_on` blocks, if they are present.
+- Place `lifecycle` blocks at the end of resource definitions.
+- Alphabetize providers, variables, data sources, resources, and outputs within each file for easier navigation.
+- Group related attributes together within blocks.
+  - Place required attributes before optional ones, and comment each section accordingly.
+  - Separate attribute sections with blank lines to improve readability.
+  - Alphabetize attributes within each section for easier navigation.
+- Use blank lines to separate logical sections of your configurations.
+- Use `terraform fmt` to format your configurations automatically.
+- Use `terraform validate` to check for syntax errors and ensure configurations are valid.
+- Use `tflint` to check for style violations and ensure configurations follow best practices.
+  - Run `tflint` regularly to catch style issues early in the development process.
+
+## Documentation
+
+- Always include `description` and `type` attributes for variables and outputs.
+  - Use clear and concise descriptions to explain the purpose of each variable and output.
+  - Use appropriate types for variables (e.g., `string`, `number`, `bool`, `list`, `map`).
+- Document your Terraform configurations using comments, where appropriate.
+  - Use comments to explain the purpose of resources and variables.
+  - Use comments to explain complex configurations or decisions.
+  - Avoid redundant comments; comments should add value and clarity.
+- Include a `README.md` file in each project to provide an overview of the project and its structure.
+  - Include instructions for setting up and using the configurations.
+- Use `terraform-docs` to generate documentation for your configurations automatically.
+
+## Testing
+
+- Write tests to validate the functionality of your Terraform configurations.
+  - Use the `.tftest.hcl` extension for test files.
+  - Write tests to cover both positive and negative scenarios.
+  - Ensure tests are idempotent and can be run multiple times without side effects.

package/assets/instructions/typescript-5-es2022.instructions.md

@@ -0,0 +1,114 @@
+---
+description: 'Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output'
+applyTo: '**/*.ts'
+---
+
+# TypeScript Development
+
+> These instructions assume projects are built with TypeScript 5.x (or newer) compiling to an ES2022 JavaScript baseline. Adjust guidance if your runtime requires older language targets or down-level transpilation.
+
+## Core Intent
+
+- Respect the existing architecture and coding standards.
+- Prefer readable, explicit solutions over clever shortcuts.
+- Extend current abstractions before inventing new ones.
+- Prioritize maintainability and clarity, short methods and classes, clean code.
+
+## General Guardrails
+
+- Target TypeScript 5.x / ES2022 and prefer native features over polyfills.
+- Use pure ES modules; never emit `require`, `module.exports`, or CommonJS helpers.
+- Rely on the project's build, lint, and test scripts unless asked otherwise.
+- Note design trade-offs when intent is not obvious.
+
+## Project Organization
+
+- Follow the repository's folder and responsibility layout for new code.
+- Use kebab-case filenames (e.g., `user-session.ts`, `data-service.ts`) unless told otherwise.
+- Keep tests, types, and helpers near their implementation when it aids discovery.
+- Reuse or extend shared utilities before adding new ones.
+
+## Naming & Style
+
+- Use PascalCase for classes, interfaces, enums, and type aliases; camelCase for everything else.
+- Skip interface prefixes like `I`; rely on descriptive names.
+- Name things for their behavior or domain meaning, not implementation.
+
+## Formatting & Style
+
+- Run the repository's lint/format scripts (e.g., `npm run lint`) before submitting.
+- Match the project's indentation, quote style, and trailing comma rules.
+- Keep functions focused; extract helpers when logic branches grow.
+- Favor immutable data and pure functions when practical.
+
+## Type System Expectations
+
+- Avoid `any` (implicit or explicit); prefer `unknown` plus narrowing.
+- Use discriminated unions for realtime events and state machines.
+- Centralize shared contracts instead of duplicating shapes.
+- Express intent with TypeScript utility types (e.g., `Readonly`, `Partial`, `Record`).
+
+## Async, Events & Error Handling
+
+- Use `async/await`; wrap awaits in try/catch with structured errors.
+- Guard edge cases early to avoid deep nesting.
+- Send errors through the project's logging/telemetry utilities.
+- Surface user-facing errors via the repository's notification pattern.
+- Debounce configuration-driven updates and dispose resources deterministically.
+
+## Architecture & Patterns
+
+- Follow the repository's dependency injection or composition pattern; keep modules single-purpose.
+- Observe existing initialization and disposal sequences when wiring into lifecycles.
+- Keep transport, domain, and presentation layers decoupled with clear interfaces.
+- Supply lifecycle hooks (e.g., `initialize`, `dispose`) and targeted tests when adding services.
+
+## External Integrations
+
+- Instantiate clients outside hot paths and inject them for testability.
+- Never hardcode secrets; load them from secure sources.
+- Apply retries, backoff, and cancellation to network or IO calls.
+- Normalize external responses and map errors to domain shapes.
+
+## Security Practices
+
+- Validate and sanitize external input with schema validators or type guards.
+- Avoid dynamic code execution and untrusted template rendering.
+- Encode untrusted content before rendering HTML; use framework escaping or trusted types.
+- Use parameterized queries or prepared statements to block injection.
+- Keep secrets in secure storage, rotate them regularly, and request least-privilege scopes.
+- Favor immutable flows and defensive copies for sensitive data.
+- Use vetted crypto libraries only.
+- Patch dependencies promptly and monitor advisories.
+
+## Configuration & Secrets
+
+- Reach configuration through shared helpers and validate with schemas or dedicated validators.
+- Handle secrets via the project's secure storage; guard `undefined` and error states.
+- Document new configuration keys and update related tests.
+
+## UI & UX Components
+
+- Sanitize user or external content before rendering.
+- Keep UI layers thin; push heavy logic to services or state managers.
+- Use messaging or events to decouple UI from business logic.
+
+## Testing Expectations
+
+- Add or update unit tests with the project's framework and naming style.
+- Expand integration or end-to-end suites when behavior crosses modules or platform APIs.
+- Run targeted test scripts for quick feedback before submitting.
+- Avoid brittle timing assertions; prefer fake timers or injected clocks.
+
+## Performance & Reliability
+
+- Lazy-load heavy dependencies and dispose them when done.
+- Defer expensive work until users need it.
+- Batch or debounce high-frequency events to reduce thrash.
+- Track resource lifetimes to prevent leaks.
+
+## Documentation & Comments
+
+- Add JSDoc to public APIs; include `@remarks` or `@example` when helpful.
+- Write comments that capture intent, and remove stale notes during refactors.
+- Update architecture or design docs when introducing significant patterns.

package/assets/instructions/typescript-mcp-server.instructions.md

@@ -0,0 +1,228 @@
+---
+description: 'Instructions for building Model Context Protocol (MCP) servers using the TypeScript SDK'
+applyTo: '**/*.ts, **/*.js, **/package.json'
+---
+
+# TypeScript MCP Server Development
+
+## Instructions
+
+- Use the **@modelcontextprotocol/sdk** npm package: `npm install @modelcontextprotocol/sdk`
+- Import from specific paths: `@modelcontextprotocol/sdk/server/mcp.js`, `@modelcontextprotocol/sdk/server/stdio.js`, etc.
+- Use `McpServer` class for high-level server implementation with automatic protocol handling
+- Use `Server` class for low-level control with manual request handlers
+- Use **zod** for input/output schema validation: `npm install zod@3`
+- Always provide `title` field for tools, resources, and prompts for better UI display
+- Use `registerTool()`, `registerResource()`, and `registerPrompt()` methods (recommended over older APIs)
+- Define schemas using zod: `{ inputSchema: { param: z.string() }, outputSchema: { result: z.string() } }`
+- Return both `content` (for display) and `structuredContent` (for structured data) from tools
+- For HTTP servers, use `StreamableHTTPServerTransport` with Express or similar frameworks
+- For local integrations, use `StdioServerTransport` for stdio-based communication
+- Create new transport instances per request to prevent request ID collisions (stateless mode)
+- Use session management with `sessionIdGenerator` for stateful servers
+- Enable DNS rebinding protection for local servers: `enableDnsRebindingProtection: true`
+- Configure CORS headers and expose `Mcp-Session-Id` for browser-based clients
+- Use `ResourceTemplate` for dynamic resources with URI parameters: `new ResourceTemplate('resource://{param}', { list: undefined })`
+- Support completions for better UX using `completable()` wrapper from `@modelcontextprotocol/sdk/server/completable.js`
+- Implement sampling with `server.server.createMessage()` to request LLM completions from clients
+- Use `server.server.elicitInput()` to request additional user input during tool execution
+- Enable notification debouncing for bulk updates: `debouncedNotificationMethods: ['notifications/tools/list_changed']`
+- Dynamic updates: call `.enable()`, `.disable()`, `.update()`, or `.remove()` on registered items to emit `listChanged` notifications
+- Use `getDisplayName()` from `@modelcontextprotocol/sdk/shared/metadataUtils.js` for UI display names
+- Test servers with MCP Inspector: `npx @modelcontextprotocol/inspector`
+
+## Best Practices
+
+- Keep tool implementations focused on single responsibilities
+- Provide clear, descriptive titles and descriptions for LLM understanding
+- Use proper TypeScript types for all parameters and return values
+- Implement comprehensive error handling with try-catch blocks
+- Return `isError: true` in tool results for error conditions
+- Use async/await for all asynchronous operations
+- Close database connections and clean up resources properly
+- Validate input parameters before processing
+- Use structured logging for debugging without polluting stdout/stderr
+- Consider security implications when exposing file system or network access
+- Implement proper resource cleanup on transport close events
+- Use environment variables for configuration (ports, API keys, etc.)
+- Document tool capabilities and limitations clearly
+- Test with multiple clients to ensure compatibility
+
+## Common Patterns
+
+### Basic Server Setup (HTTP)
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+
+const server = new McpServer({
+    name: 'my-server',
+    version: '1.0.0'
+});
+
+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);
+});
+
+app.listen(3000);
+```
+
+### Basic Server Setup (stdio)
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new McpServer({
+    name: 'my-server',
+    version: '1.0.0'
+});
+
+// ... register tools, resources, prompts ...
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### Simple Tool
+```typescript
+import { z } from 'zod';
+
+server.registerTool(
+    'calculate',
+    {
+        title: 'Calculator',
+        description: 'Perform basic calculations',
+        inputSchema: { a: z.number(), b: z.number(), op: z.enum(['+', '-', '*', '/']) },
+        outputSchema: { result: z.number() }
+    },
+    async ({ a, b, op }) => {
+        const result = op === '+' ? a + b : op === '-' ? a - b : 
+                      op === '*' ? a * b : a / b;
+        const output = { result };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output) }],
+            structuredContent: output
+        };
+    }
+);
+```
+
+### Dynamic Resource
+```typescript
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+server.registerResource(
+    'user',
+    new ResourceTemplate('users://{userId}', { list: undefined }),
+    {
+        title: 'User Profile',
+        description: 'Fetch user profile data'
+    },
+    async (uri, { userId }) => ({
+        contents: [{
+            uri: uri.href,
+            text: `User ${userId} data here`
+        }]
+    })
+);
+```
+
+### Tool with Sampling
+```typescript
+server.registerTool(
+    'summarize',
+    {
+        title: 'Text Summarizer',
+        description: 'Summarize text using LLM',
+        inputSchema: { text: z.string() },
+        outputSchema: { summary: z.string() }
+    },
+    async ({ text }) => {
+        const response = await server.server.createMessage({
+            messages: [{
+                role: 'user',
+                content: { type: 'text', text: `Summarize: ${text}` }
+            }],
+            maxTokens: 500
+        });
+        
+        const summary = response.content.type === 'text' ? 
+            response.content.text : 'Unable to summarize';
+        const output = { summary };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output) }],
+            structuredContent: output
+        };
+    }
+);
+```
+
+### Prompt with Completion
+```typescript
+import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
+
+server.registerPrompt(
+    'review',
+    {
+        title: 'Code Review',
+        description: 'Review code with specific focus',
+        argsSchema: {
+            language: completable(z.string(), value => 
+                ['typescript', 'python', 'javascript', 'java']
+                    .filter(l => l.startsWith(value))
+            ),
+            code: z.string()
+        }
+    },
+    ({ language, code }) => ({
+        messages: [{
+            role: 'user',
+            content: {
+                type: 'text',
+                text: `Review this ${language} code:\n\n${code}`
+            }
+        }]
+    })
+);
+```
+
+### Error Handling
+```typescript
+server.registerTool(
+    'risky-operation',
+    {
+        title: 'Risky Operation',
+        description: 'An operation that might fail',
+        inputSchema: { input: z.string() },
+        outputSchema: { result: z.string() }
+    },
+    async ({ input }) => {
+        try {
+            const result = await performRiskyOperation(input);
+            const output = { result };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output
+            };
+        } catch (err: unknown) {
+            const error = err as Error;
+            return {
+                content: [{ type: 'text', text: `Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+);
+```