diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 0000000..9f6163c --- /dev/null +++ b/.github/workflows/publish.yaml @@ -0,0 +1,66 @@ +name: Publish to JSR + +on: + push: + tags: + - 'v*.*.*' + workflow_dispatch: + inputs: + version: + description: 'Version to publish (e.g., 1.0.0)' + required: true + type: string + +jobs: + publish: + name: Publish Package + runs-on: ubuntu-latest + + permissions: + contents: read + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Deno + uses: denoland/setup-deno@v1 + with: + deno-version: v2.x + + - name: Verify formatting + run: deno fmt --check + + - name: Run linter + run: deno lint + + - name: Type check + run: deno task check + + - name: Run tests + run: deno task test + + - name: Extract version from tag or input + id: version + run: | + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + VERSION="${{ github.event.inputs.version }}" + else + VERSION=${GITHUB_REF#refs/tags/v} + fi + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "Publishing version: $VERSION" + + - name: Update version in deno.jsonc + run: | + VERSION="${{ steps.version.outputs.version }}" + sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" deno.jsonc + echo "Updated deno.jsonc version to $VERSION" + cat deno.jsonc | grep version + + - name: Generate version.ts from deno.jsonc + run: deno task update-version + + - name: Publish to JSR + run: deno publish --allow-dirty diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml new file mode 100644 index 0000000..8a21d86 --- /dev/null +++ b/.github/workflows/test.yaml @@ -0,0 +1,51 @@ +name: Test + +on: + push: + branches: + - main + - develop + pull_request: + branches: + - main + - develop + +jobs: + test: + name: Run Tests + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Deno + uses: denoland/setup-deno@v1 + with: + deno-version: v2.x + + - name: Verify formatting + run: deno fmt --check + + - name: Run linter + run: deno task lint + + - name: Type check + run: deno task check + + - name: Run tests + run: deno task test + + - name: Generate coverage + run: deno task test:coverage + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + with: + files: ./tests/coverage/lcov.info + fail_ci_if_error: false + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} diff --git a/.gitignore b/.gitignore index f1c6337..ef5ea8e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ .trash/ .BBEditLSPWorkspaceConfig.json -node_modules \ No newline at end of file +node_modules +coverage \ No newline at end of file diff --git a/GUIDELINES.md b/GUIDELINES.md index 863fc9e..8f56820 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -10,11 +10,16 @@ purpose: Guidelines for ongoing maintenance and development of the MCP Server Cl ## Project Overview -The **MCP Server Client Inspector** is a comprehensive testing platform for MCP (Model Context Protocol) client implementations. It provides an interactive web console for testing and validating MCP clients through an MCP server that offers inspection tools, sampling, elicitation, and notification testing capabilities. +The **MCP Server Client Inspector** is a comprehensive testing platform for MCP +(Model Context Protocol) client implementations. It provides an interactive web +console for testing and validating MCP clients through an MCP server that offers +inspection tools, sampling, elicitation, and notification testing capabilities. -**Key Purpose**: While the MCP Inspector tests MCP servers, this project fills the inverse need - an MCP server for testing MCP clients. +**Key Purpose**: While the MCP Inspector tests MCP servers, this project fills +the inverse need - an MCP server for testing MCP clients. **Technology Stack**: + - Runtime: Deno 2.5+ - MCP Framework: bb-mcp-server library - UI Framework: Deno Fresh with Preact Islands @@ -23,7 +28,8 @@ The **MCP Server Client Inspector** is a comprehensive testing platform for MCP - Storage: Deno KV - Language: TypeScript with strict mode -**Project Status**: New project with comprehensive design documentation; ready for implementation and ongoing maintenance. +**Project Status**: New project with comprehensive design documentation; ready +for implementation and ongoing maintenance. ## Project Structure and Organization @@ -63,20 +69,26 @@ bb-mcp-server-client-inspector/ ### Code Organization Rules **Shared Directory**: + - **Use for**: Code needed by BOTH mcp-server and fresh-ui - **Examples**: Type definitions, interfaces, constants, utilities used by both -- **Don't use for**: Server-specific logic, UI-specific logic, single-use utilities +- **Don't use for**: Server-specific logic, UI-specific logic, single-use + utilities **Plugin Architecture**: + - Multiple plugins are allowed and encouraged - Organize plugins by functional category (no strict rules) - Example categories: inspector tools, testing utilities, monitoring - New inspector tools can be added to existing inspector.plugin or new plugins **Fresh Islands vs Components**: -- **Islands**: Required for any browser interactivity (event handlers, state management) + +- **Islands**: Required for any browser interactivity (event handlers, state + management) - **Components**: Static rendering, no browser JavaScript needed -- **Common Pattern**: 1-2 top-level parent islands with components loaded by the island +- **Common Pattern**: 1-2 top-level parent islands with components loaded by the + island - **Performance**: Keep islands minimal; use components wherever possible ## Development Workflow @@ -102,6 +114,7 @@ bb-mcp-server-client-inspector/ ### Documentation Maintenance **Critical Documents** (must keep updated): + 1. **ARCHITECTURE.md** - Update when system architecture changes 2. **WEBSOCKET_PROTOCOL.md** - Update when WebSocket protocol changes 3. **README.md** - Keep current with: @@ -112,11 +125,13 @@ bb-mcp-server-client-inspector/ 4. **.env.example** - Update when new config options are added **Reference Documents** (update as needed): + - Other docs in `docs/` are primarily for initial implementation - Update if they contain information that's helpful for ongoing work - Don't worry about keeping them perfectly in sync **When to Ask for Clarification**: + - Documentation is unclear or contradictory - Examples don't match current code structure - Requirements seem ambiguous or incomplete @@ -133,6 +148,7 @@ bb-mcp-server-client-inspector/ - Include sensible defaults in code for optional settings **Example `.env.example` structure**: + ```bash # Server Configuration PORT=8000 @@ -151,27 +167,31 @@ LOG_LEVEL=info ### TypeScript Style **Formatting**: + - Use Deno/TypeScript default formatting - 2 space indentation - Strict TypeScript mode enabled - Run `deno fmt` before committing **Comments**: + - Average comment density (not sparse, not excessive) - Explain "why" not "what" in comments - Comment complex algorithms or non-obvious logic **JSDoc**: + - Thorough JSDoc for all public APIs - Include @param, @returns, @throws as appropriate - Keep descriptions concise but complete - Not necessary to document every private function **Example**: + ```typescript /** * Triggers a notification to all connected clients. - * + * * @param notificationType - Type of notification (tools/resources/prompts) * @param sessionId - Optional session ID to target specific client * @returns Promise resolving to number of clients notified @@ -179,7 +199,7 @@ LOG_LEVEL=info */ export async function triggerNotification( notificationType: NotificationType, - sessionId?: string + sessionId?: string, ): Promise { // Implementation } @@ -188,6 +208,7 @@ export async function triggerNotification( ### Error Handling **Requirements**: + - Comprehensive error handling throughout - Follow established patterns from bb-mcp-server and MCP SDK - No specific error format required, but be consistent @@ -195,8 +216,9 @@ export async function triggerNotification( - Log errors with appropriate context **Pattern Example**: + ```typescript -import { isError, errorMessage } from '@beyondbetter/bb-mcp-server'; +import { errorMessage, isError } from '@beyondbetter/bb-mcp-server'; try { await performOperation(); @@ -204,9 +226,9 @@ try { logger.error('Operation failed', { operation: 'performOperation', error: errorMessage(error), - context: { /* relevant context */ } + context: {/* relevant context */}, }); - + if (isError(error)) { throw new Error(`Failed to perform operation: ${error.message}`); } else { @@ -218,6 +240,7 @@ try { ### Dependencies **Guidelines**: + - No restrictions on adding dependencies - Prefer Deno-native solutions when available - Use JSR packages where possible @@ -225,6 +248,7 @@ try { - Keep dependencies up to date **Core Dependencies** (already established): + - @modelcontextprotocol/sdk - @beyondbetter/bb-mcp-server - Deno Fresh framework @@ -237,21 +261,25 @@ try { ### DaisyUI Component Framework **Overview**: + - DaisyUI is the primary component library for fresh-ui - Built on top of Tailwind CSS utility classes - Provides semantic, accessible components with consistent theming - No JavaScript required for most components (perfect for Fresh components) - Interactive components work seamlessly with Fresh islands -**DaisyUI MCP Server**: -This project has access to a DaisyUI MCP server with the following tools: +**DaisyUI MCP Server**: This project has access to a DaisyUI MCP server with the +following tools: + - `fetch_daisyui_documentation_daisyui` - Fetch entire documentation files - `search_daisyui_documentation_daisyui` - Semantic search within DaisyUI docs - `search_daisyui_code_daisyui` - Search DaisyUI repository code - `fetch_generic_url_content_daisyui` - Fetch referenced URLs from documentation **When to Use DaisyUI Tools**: -- Before creating new UI components, search DaisyUI docs for appropriate components + +- Before creating new UI components, search DaisyUI docs for appropriate + components - When unsure about component APIs or available variants - To find code examples and usage patterns - To discover theming and customization options @@ -259,13 +287,14 @@ This project has access to a DaisyUI MCP server with the following tools: ### Component Implementation Guidelines **Fresh Components (Static)**: + ```typescript // components/MessageCard.tsx -import { JSX } from "preact"; +import { JSX } from 'preact'; interface MessageCardProps { message: string; - type: "info" | "success" | "warning" | "error"; + type: 'info' | 'success' | 'warning' | 'error'; } export function MessageCard({ message, type }: MessageCardProps): JSX.Element { @@ -278,20 +307,21 @@ export function MessageCard({ message, type }: MessageCardProps): JSX.Element { ``` **Fresh Islands (Interactive)**: + ```typescript // islands/ConsoleControls.tsx -import { useState } from "preact/hooks"; -import { JSX } from "preact"; +import { useState } from 'preact/hooks'; +import { JSX } from 'preact'; export default function ConsoleControls(): JSX.Element { const [isActive, setIsActive] = useState(false); - + return ( -
-
-

Console Controls

-
- @@ -345,6 +381,7 @@ export default function ConsoleControls(): JSX.Element { ``` **Combining with Tailwind**: + ```html
@@ -355,9 +392,11 @@ export default function ConsoleControls(): JSX.Element { ``` **Theming**: + - DaisyUI includes multiple built-in themes - Configure theme in `fresh.config.ts` or HTML data attributes -- Use semantic color names: `primary`, `secondary`, `accent`, `neutral`, `base-100`, etc. +- Use semantic color names: `primary`, `secondary`, `accent`, `neutral`, + `base-100`, etc. - Theme switching can be added as a future feature ### Component Development Workflow @@ -366,7 +405,7 @@ export default function ConsoleControls(): JSX.Element { ```typescript // Example: Search for alert component documentation await search_daisyui_documentation_daisyui({ - query: "alert component API" + query: 'alert component API', }); ``` @@ -393,56 +432,60 @@ export default function ConsoleControls(): JSX.Element { ### Common Patterns for This Project **Message Display**: + ```typescript // Use alert component for system messages -
+
... WebSocket connected -
+
; ``` **Message List**: + ```typescript // Use card or timeline for message history -
-
-
+
+
+
...
-
-
-

Sampling Request

+
+
+

Sampling Request

Request content...

-
+
; ``` **Control Panel**: + ```typescript // Use card with form controls -
-
-

Test Controls

-
-