@jaypie/mcp 0.3.2 → 0.4.0

package/prompts/Jaypie_MCP_Package.md

@@ -1,281 +0,0 @@
----
-description: MCP server package with documentation, AWS, Datadog, and LLM tools
-include: "packages/mcp/**"
----
-
-# @jaypie/mcp Package
-
-The `@jaypie/mcp` package provides a Model Context Protocol (MCP) server for AI agents working with Jaypie projects. It includes tools for accessing documentation, AWS CLI operations, Datadog observability, and LLM debugging.
-
-## Package Structure
-
-```
-packages/mcp/
-├── src/
-│   ├── index.ts              # CLI entrypoint, exports createMcpServer and mcpExpressHandler
-│   ├── createMcpServer.ts    # Core MCP server factory with tool definitions
-│   ├── mcpExpressHandler.ts  # Express middleware for HTTP transport
-│   ├── aws.ts                # AWS CLI integration (spawn-based)
-│   ├── datadog.ts            # Datadog API integration (https-based)
-│   └── llm.ts                # LLM debug utilities
-├── prompts/                  # Markdown guides served via list_prompts/read_prompt tools
-├── release-notes/            # Version history by package (e.g., release-notes/mcp/0.3.2.md)
-└── dist/                     # Built output
-```
-
-## Usage
-
-### CLI (stdio transport)
-
-```bash
-npx jaypie-mcp          # Run MCP server via stdio
-npx jaypie-mcp --verbose # Run with debug logging
-```
-
-### Express Integration (HTTP transport)
-
-```typescript
-import express from "express";
-import { mcpExpressHandler } from "@jaypie/mcp";
-
-const app = express();
-app.use(express.json());
-app.use("/mcp", await mcpExpressHandler({ version: "1.0.0" }));
-```
-
-### Direct Server Creation
-
-```typescript
-import { createMcpServer } from "@jaypie/mcp";
-
-const server = createMcpServer({ version: "1.0.0", verbose: true });
-```
-
-## MCP Tools (29 total)
-
-### Documentation Tools (5)
-
-| Tool | Description |
-|------|-------------|
-| `list_prompts` | Lists all `.md` files in `prompts/` with descriptions and required file patterns |
-| `read_prompt` | Returns content of a specific prompt file |
-| `version` | Returns package version string |
-| `list_release_notes` | Lists release notes by package, supports `since_version` filtering |
-| `read_release_note` | Returns full content of a specific release note |
-
-### AWS CLI Tools (16)
-
-Requires AWS CLI installed and configured. All tools accept optional `profile` and `region` parameters.
-
-| Tool | Description |
-|------|-------------|
-| `aws_list_profiles` | List available AWS profiles from ~/.aws/config and credentials |
-| `aws_stepfunctions_list_executions` | List Step Function executions for a state machine |
-| `aws_stepfunctions_stop_execution` | Stop a running Step Function execution |
-| `aws_lambda_list_functions` | List Lambda functions with optional prefix filtering |
-| `aws_lambda_get_function` | Get configuration and details for a specific Lambda function |
-| `aws_logs_filter_log_events` | Search CloudWatch Logs with pattern and time range filtering |
-| `aws_s3_list_objects` | List objects in an S3 bucket with optional prefix filtering |
-| `aws_cloudformation_describe_stack` | Get details and status of a CloudFormation stack |
-| `aws_dynamodb_describe_table` | Get metadata about a DynamoDB table |
-| `aws_dynamodb_scan` | Scan a DynamoDB table (use sparingly on large tables) |
-| `aws_dynamodb_query` | Query a DynamoDB table by partition key |
-| `aws_dynamodb_get_item` | Get a single item from a DynamoDB table by primary key |
-| `aws_sqs_list_queues` | List SQS queues with optional prefix filtering |
-| `aws_sqs_get_queue_attributes` | Get queue attributes including message counts |
-| `aws_sqs_receive_message` | Peek at messages in an SQS queue (does not delete) |
-| `aws_sqs_purge_queue` | Delete all messages from an SQS queue (irreversible) |
-
-### Datadog Tools (6)
-
-Requires `DATADOG_API_KEY` and `DATADOG_APP_KEY` environment variables.
-
-| Tool | Description |
-|------|-------------|
-| `datadog_logs` | Search individual log entries |
-| `datadog_log_analytics` | Aggregate logs with groupBy operations |
-| `datadog_monitors` | List and filter monitors by status/tags |
-| `datadog_synthetics` | List synthetic tests or get results for a specific test |
-| `datadog_metrics` | Query timeseries metrics |
-| `datadog_rum` | Search Real User Monitoring events |
-
-### LLM Tools (2)
-
-| Tool | Description |
-|------|-------------|
-| `llm_debug_call` | Debug LLM API calls and inspect raw responses |
-| `llm_list_providers` | List available LLM providers with their models |
-
-## Environment Variables
-
-### AWS CLI Integration
-
-| Variable | Description |
-|----------|-------------|
-| `AWS_PROFILE` | Default profile if not specified per-call |
-| `AWS_REGION` or `AWS_DEFAULT_REGION` | Default region if not specified |
-
-AWS tools use the host's existing credential chain:
-- `~/.aws/credentials` and `~/.aws/config` files
-- Environment variables (`AWS_ACCESS_KEY_ID`, etc.)
-- SSO sessions established via `aws sso login`
-
-### Datadog Integration
-
-| Variable | Description |
-|----------|-------------|
-| `DATADOG_API_KEY` or `DD_API_KEY` | Datadog API key |
-| `DATADOG_APP_KEY` or `DD_APP_KEY` | Datadog Application key |
-| `DD_ENV` | Default environment filter |
-| `DD_SERVICE` | Default service filter |
-| `DD_SOURCE` | Default log source (defaults to "lambda") |
-| `DD_QUERY` | Default query terms appended to searches |
-
-## Adding New Tools
-
-Tools are registered in `createMcpServer.ts` using the MCP SDK pattern:
-
-```typescript
-server.tool(
-  "tool_name",
-  "Description shown to AI agents",
-  {
-    // Zod schema for parameters
-    param1: z.string().describe("Parameter description"),
-    param2: z.number().optional().describe("Optional parameter"),
-  },
-  async ({ param1, param2 }) => {
-    // Implementation
-    return {
-      content: [{ type: "text" as const, text: "Result text" }],
-    };
-  },
-);
-```
-
-### AWS Tool Pattern
-
-AWS tools use `child_process.spawn` to call the AWS CLI:
-
-```typescript
-// In aws.ts
-export async function myAwsOperation(
-  options: MyOperationOptions,
-  logger: Logger = nullLogger,
-): Promise<AwsCommandResult<MyResultType>> {
-  const args = ["--required-arg", options.requiredArg];
-  if (options.optionalArg) {
-    args.push("--optional-arg", options.optionalArg);
-  }
-
-  return executeAwsCommand(
-    "service-name",    // e.g., "stepfunctions", "lambda", "s3api"
-    "command-name",    // e.g., "list-executions", "get-function"
-    args,
-    { profile: options.profile, region: options.region },
-    logger,
-  );
-}
-```
-
-### Datadog Tool Pattern
-
-Datadog tools use Node.js `https` module directly:
-
-```typescript
-// In datadog.ts
-export async function myDatadogOperation(
-  credentials: DatadogCredentials,
-  options: MyOptions,
-  logger: Logger = nullLogger,
-): Promise<MyResult> {
-  const requestOptions = {
-    hostname: "api.datadoghq.com",
-    port: 443,
-    path: "/api/v2/endpoint",
-    method: "POST",
-    headers: {
-      "DD-API-KEY": credentials.apiKey,
-      "DD-APPLICATION-KEY": credentials.appKey,
-      "Content-Type": "application/json",
-    },
-  };
-
-  return new Promise((resolve) => {
-    const req = https.request(requestOptions, (res) => {
-      // Handle response
-    });
-    req.write(JSON.stringify(body));
-    req.end();
-  });
-}
-```
-
-## Adding New Prompts
-
-Prompts are markdown files in `prompts/` with optional YAML frontmatter:
-
-```yaml
----
-description: Brief description shown in list_prompts
-include: "packages/express/**"  # File patterns this guide applies to
----
-
-# Prompt Title
-
-Markdown content here...
-```
-
-Prompts are automatically available via `list_prompts` and `read_prompt` tools.
-
-## Adding New Release Notes
-
-Release notes are organized by package in `release-notes/`:
-
-```
-release-notes/
-├── jaypie/
-│   └── 1.2.3.md
-└── mcp/
-    └── 0.3.2.md
-```
-
-Each release note uses YAML frontmatter:
-
-```yaml
----
-version: 0.3.2
-date: 2025-01-19
-summary: Brief one-line summary for listing
----
-
-## Changes
-
-- Feature 1
-- Bug fix 2
-```
-
-Release notes are automatically available via `list_release_notes` and `read_release_note` tools. The `since_version` parameter allows clients to query only releases newer than a specific version.
-
-## Exports
-
-```typescript
-import { createMcpServer, mcpExpressHandler } from "@jaypie/mcp";
-import type { CreateMcpServerOptions, McpExpressHandlerOptions } from "@jaypie/mcp";
-```
-
-## Commands
-
-```bash
-npm run build -w packages/mcp      # Build with rollup
-npm run test -w packages/mcp       # Run tests (vitest run)
-npm run typecheck -w packages/mcp  # Type check (tsc --noEmit)
-npm run format packages/mcp        # Format with eslint --fix
-```
-
-## Security Considerations
-
-1. **Allowlisted operations only** - No arbitrary command execution
-2. **Read-heavy design** - Most tools are read-only; mutating operations have explicit warnings
-3. **No credential exposure** - Credentials never passed through MCP; uses host's credential chain
-4. **Profile isolation** - Each call can specify a different profile for multi-account work

package/prompts/Jaypie_Mocks_and_Testkit.md

@@ -1,137 +0,0 @@
----
-description: Jaypie projects rely heavily on mocking the entire jaypie package, often in setup files, as well as manual mocks. Recommended when creating new tests or addressing failures.
----
-
-# Jaypie Mocks and Testkit
-
-Adds unit tests for a JavaScript or TypeScript file.
-
-## Requirements
-
-- Use **Vitest** for all test files.
-- Create a new test file as a sibling to the implementation, not a separate directory or tree
-- Use **ECMAScript module syntax** (`import/export`), not CommonJS.
-- Import the function under test using a relative path and include the `.js` extension.
-- Use `describe` blocks for each function and `it` blocks for each behavior.
-- Include tests for:
-  - Normal/expected input
-  - Edge cases
-  - Error handling (if applicable)
-- Ensure all tests are deterministic and do not rely on randomness or network calls unless mocked.
-
-## File Style Rules
-
-- Use double quotes.
-- Use ES6+ syntax.
-- Do not modify the original file.
-- Do not include any setup or installation instructions.
-
-## Jaypie Testkit
-`@jaypie/testkit` is the testing library.
-`matchers` are exported and extend expect in the test setup.
-All jaypie functions can be mocked with `vi.mock("jaypie", async () => vi.importActual("@jaypie/testkit/mock"));`
-### Classes
-Mocked jaypie classes should mocked members for each mocked implementation.
-```
-Llm.operate.mockResolvedValue("Bueno");
-const llm = new Llm();
-const response = llm.operate();
-expect(response).toBeString("Bueno");
-expect(Llm.operate).toHaveBeenCalled()
-```
-### Errors
-Use matchers to test errors.
-`expect(fn).toThrowBadGatewayError();`
-`await expect(async() => fn()).toThrowBadGatewayError();`
-Do not use `.rejects`
-### Express
-Most express functions are wrapped in `expressHandler` which is mocked.
-Test express functions directly with a `req` object.
-Handle cases where the `req` object is undefined or incomplete.
-supertest is also available to test http responses.
-### Logging
-`log` is mocked by `@jaypie/testkit/mock` or separately using `spyLog` and `restoreLog` in `@jaypie/testkit`.
-Use matchers on `log` functions and `toBeCalledAboveTrace` on `log` itself.
-`expect(log).not.toBeCalledAboveTrace();`
-`expect(log.warn).toBeCalled();`
-### Matchers
-toBeCalledAboveTrace, toBeCalledWithInitialParams, toBeClass, toBeJaypieError, toMatchBase64, toMatchJwt, toMatchMongoId, toMatchSchema, toMatchSignedCookie, toMatchUuid4, toMatchUuid5, toMatchUuid, toThrowBadGatewayError, toThrowBadRequestError, toThrowConfigurationError, toThrowForbiddenError, toThrowGatewayTimeoutError, toThrowInternalError, toThrowJaypieError, toThrowNotFoundError, toThrowUnauthorizedError, toThrowUnavailableError,
-### Order of Tests
-Tests are named `./__tests__/<subject>.spec.<js|ts>`.
-Each file should have one top-level `describe` block.
-Organize tests in one of seven second-level describe block sections in this order:
-1. Base Cases - it is the type we expect ("It is a Function"). For functions, the simplest possible call works and returns not undefined ("It Works"). For objects, the expected shape.
-2. Error Conditions - any error handling the code performs
-3. Security - any security checks the code performs
-4. Observability - any logging the code performs
-5. Happy Paths - The most common use case
-6. Features - Features in addition to the happy path
-7. Specific Scenarios - Special cases
-Omit describe blocks for sections that are not applicable or empty.
-Whenever possible, especially when refactoring, write the test first so the user can confirm the expected behavior passes/fails.
-### Test Coverage
-Aim for complete coverage of all happy paths, features, and error conditions.
-Whenever possible, confirm mocked functions are called.
-Confirm calls to log above debug in Observability. Do not confirm calls to debug, var, or trace.
-
-## Configuration
-
-### Typical Package
-
-`package.json`
-```json
-"scripts": {
-  "test": "vitest run",
-  "test:watch": "vitest watch",
-}
-```
-
-`vitest.config.ts`
-```typescript
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  test: {
-    setupFiles: ["./vitest.setup.ts"],
-  },
-});
-```
-
-`vitest.setup.ts`
-```typescript
-// This file left intentionally blank
-```
-
-* `vitest.setup.ts` can be used to extend the jest matchers, for example, or setting up other mocks
-```typescript
-import * as extendedMatchers from "jest-extended";
-import { expect } from "vitest";
-
-expect.extend(extendedMatchers);
-```
-* Before creating a `vitest.setup.ts`, check if `testSetup.js` exists.
-
-## NPM Workspaces (monorepos)
-
-* Configure sub-packages following the above
-* Usually only sub-packages have `vitest.config.ts` and `vitest.setup.ts`
-* Configure the root package as follows, iterating for each `<package>` below
-
-`package.json`
-```json
-"scripts": {
-  "test": "vitest run",
-  "test:watch": "vitest watch",
-  "test:<package>": "npm run test --workspace packages/<package>"
-  "test:<package>:watch": "npm run test:watch --workspace packages/<package>"
-}
-```
-
-`vitest.workspace.ts`
-```typescript
-import { defineWorkspace } from "vitest/config";
-
-export default defineWorkspace([
-  "packages/<package>",
-]);
-```

package/prompts/Jaypie_Repokit.md

@@ -1,103 +0,0 @@
----
-description: development utilities bundle for Jaypie repositories
----
-
-# Jaypie Repokit
-
-Essential development utilities bundled for Jaypie repositories. Provides common tools needed for build scripts, development workflows, and repository maintenance.
-
-## Installation
-
-```sh
-npm install --save-dev @jaypie/repokit
-```
-
-## Exported Utilities
-
-### dotenv
-
-Re-exports everything from `dotenv` for environment variable management.
-
-```typescript
-import { config } from "@jaypie/repokit";
-
-config(); // Load .env file
-```
-
-### rimraf
-
-Re-exports `rimraf` for cross-platform file deletion.
-
-```typescript
-import { rimraf } from "@jaypie/repokit";
-
-await rimraf("./dist");
-```
-
-## CLI Tools (via npx)
-
-The package includes CLI tools as dependencies that can be run via npx or in package.json scripts:
-
-### env-cmd
-
-Run commands with environment variables from a file.
-
-```json
-{
-  "scripts": {
-    "start:dev": "env-cmd -f .env.development node server.js"
-  }
-}
-```
-
-### sort-package-json
-
-Sort package.json files for consistent formatting.
-
-```json
-{
-  "scripts": {
-    "format:package": "sort-package-json ./package.json"
-  }
-}
-```
-
-### tsx
-
-Run TypeScript files directly without compilation.
-
-```json
-{
-  "scripts": {
-    "bin:script": "tsx scripts/my-script.ts"
-  }
-}
-```
-
-## Common Usage Patterns
-
-### Build Scripts
-
-```json
-{
-  "scripts": {
-    "clean": "rimraf ./dist",
-    "format:package": "sort-package-json ./package.json",
-    "bin:setup": "tsx scripts/setup.ts"
-  }
-}
-```
-
-### Environment Management
-
-```typescript
-// scripts/deploy.ts
-import { config } from "@jaypie/repokit";
-
-config({ path: ".env.production" });
-console.log(process.env.API_KEY);
-```
-
-## Why Use Repokit
-
-Instead of installing `dotenv`, `rimraf`, `env-cmd`, `sort-package-json`, and `tsx` individually in each package, install `@jaypie/repokit` once to get all essential development utilities. This ensures consistent versions across all Jaypie repositories.

package/prompts/Jaypie_Scrub.md

@@ -1,177 +0,0 @@
----
-description: House style beyond linting to keep the repository clean and organized
----
-
-# Jaypie Scrub File 🧽
-
-Repository style rules beyond linting
-
-## 🚒 Errors
-
-Jaypie offers a number of HTTP and special-use errors not limited to:
-`import { BadGatewayError, BadRequestError, ConfigurationError, ForbiddenError, InternalError, NotFoundError, TooManyRequestsError, UnauthorizedError } from "jaypie";`
-
-### Prefer to Throw Jaypie Errors
-
-* BadGatewayError when an external provider errors
-* InternalError for default 500 errors
-* ConfigurationError is a 500 variant when the problem is traceable to the coding or configuration of the system (incorrect type, incompatible options)
-
-<Bad>
-if (!item) {
-  log.error("Item not found");
-  return {
-    statusCode: 404,
-    body: JSON.stringify({ error: "Item not found" }),
-  };
-}
-</Bad>
-<Good>
-log.error("Item not found");
-throw new NotFoundError();
-</Good>
-
-### Throw Jaypie Errors to Return HTTP Errors in Express
-
-Inside a Jaypie `expressHandler`, thrown Jaypie errors will return the correct status to the client.
-Never try to alter `res` or return an error status code.
-
-### Avoid Custom Error Strings
-
-Though supported, rely on default error messages when throwing.
-Custom error messages should be logged.
-
-<Bad>
-throw new NotFoundError("Item not found");
-</Bad>
-<Good>
-log.error("Item not found");
-throw new NotFoundError();
-</Good>
-
-## 🧹 Linting
-
-Use double quotes, trailing commas, and semicolons.
-Do not delete `// eslint-disable-next-line no-shadow` comments; add when shadowing variables, especially `error` in catch blocks.
-
-## 📢 Logging
-
-### Levels
-
-* Only use `log.trace` in the happy path
-* Use `log.debug` when straying from the happy path
-* Use `log.warn`, `log.error` as needed
-* Avoid the use of `info`
-
-### Logging Variables
-
-* Log variables with `log.var({ item })`
-* Only use single-key objects
-* The key can be changed for clarity
-* When logging large arrays, objects, and strings, consider logging abridged/truncated value or summary heuristics like length
-
-### Do Not Mix Strings and Objects
-
-<Bad>
-log.trace("Looking up item", { item: item.id });
-</Bad>
-<Good>
-log.trace(`Looking up item ${item.id}`);
-# OR
-log.trace(`Looking up item`);
-log.var({ item: item.id });
-</Good>
-
-### Separate Variables
-
-Do not combine into a single call:
-
-<Bad>
-log.debug({ userId: String(user.id), groupId: String(user.group) });
-</Bad>
-<Good>
-log.var({ userId: user.id });
-log.var({ groupId: user.group }); // Jaypie will coerce strings
-</Good>
-
-### Logging in Catch Statements
-
-* Log the highest level first
-* Use warn for errors that are part of normal operations like items not found, unauthorized users
-* Use error for things that should not happen like database connections failing
-* Follow up with lower-level debug and var logs as needed
-
-### Prefixing
-
-Using a prefix in square brackets helps identify functions and libraries.
-`log.trace("[newRoute] Starting route");`
-
-## 📛 Naming Things
-
-### Pluralization
-
-* Prefer singular
-* Objects should be singular
-* A model is singular. `Model.User`
-* Arrays should be plural
-
-## 🧪 Testing
-
-Aim for complete coverage of all happy paths, features, and error conditions.
-Whenever possible, confirm mocked functions are called.
-
-### Errors
-
-Jaypie Testkit includes custom matchers for errors: toBeJaypieError, toThrowBadGatewayError, toThrowBadRequestError, toThrowConfigurationError, toThrowForbiddenError, toThrowGatewayTimeoutError, toThrowInternalError, toThrowJaypieError, toThrowNotFoundError, toThrowUnauthorizedError, toThrowUnavailableError,
-`expect(fn).toThrowBadGatewayError();`
-`await expect(async() => fn()).toThrowBadGatewayError();`
-Do not use `.rejects`
-
-### Function Calls
-
-* Always test a function was called before testing specific values
-```
-expect(fn).toBeCalled();
-expect(fn).toBeCalledWith(12);
-```
-Avoid overly specific tests on mock values and strings, especially log string.
-Test key values that need to be passed through the application.
-Use asymmetric matchers for mock values and strings.
-
-### Mocks
-
-* Assume `jaypie` is mocked by `@jaypie/testkit/mock`
-* Both of these should be mocked in the subpackage's `testSetup.js` or `vitest.setup.ts`
-
-### No Test Code in Implementations
-
-Do not check for test conditions, environment variables, or mocks outside the test logic.
-Production code should never have special handling for test cases.
-All code should be structured to be fully mockable.
-Appropriate use of mocks should allow special handling to be dictated in the test file.
-
-### Observability
-
-* The primary happy path should check `log.not.toBeCalledAboveTrace()`
-* Check `expect(log.warn).toBeCalled();` for `warn` and `error` on error cases
-* Do not confirm calls to debug, var, or trace.
-
-### Organization
-
-Each file should have one top-level `describe` block.
-Organize tests in one of seven second-level describe block sections in this order:
-
-1. Base Cases - it is the type we expect ("It is a Function"). For functions, the simplest possible call works and returns not undefined ("It Works"). For objects, the expected shape.
-2. Error Conditions - any error handling the code performs
-3. Security - any security checks the code performs
-4. Observability - any logging the code performs
-5. Happy Paths - The most common use case
-6. Features - Features in addition to the happy path
-7. Specific Scenarios - Special cases
-
-Omit describe blocks for sections that are not applicable or empty.
-
-## 🍱 Miscellaneous
-
-Alphabetize as much as possible.
-Whenever a hard-coded value like `site: "datadoghq.com"` is used, define a constant at the top of the file, `const DATADOG_SITE = "datadoghq.com"`, and reference that throughout.