CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Deno workspace containing two packages:

1. @wyattjoh/jsr - A TypeScript client library for the JSR (JavaScript Registry) API
2. @wyattjoh/jsr-mcp - A Model Context Protocol (MCP) server that exposes JSR functionality to AI assistants

The workspace structure follows Deno best practices with separate packages that can be independently published to JSR.

Workspace Structure

/
├── deno.json                 # Workspace configuration
├── packages/
│   ├── jsr/                  # JSR client library package
│   │   ├── deno.json        # Package configuration
│   │   ├── mod.ts           # Main exports
│   │   ├── src/
│   │   │   ├── client.ts    # JSR API client implementation
│   │   │   └── types.ts     # TypeScript types and Zod schemas
│   │   └── tests/
│   │       └── client.test.ts
│   └── jsr-mcp/             # MCP server package
│       ├── deno.json        # Package configuration
│       ├── mod.ts           # Main entry point
│       ├── src/
│       │   └── index.ts     # MCP server implementation with inline tool definitions
│       └── tests/
│           └── server.test.ts

Development Commands

Workspace-level commands (run from root):

• Format all code: deno fmt
• Lint all code: deno lint
• Type check all code: deno check packages/jsr/mod.ts packages/jsr-mcp/mod.ts
• Run all tests: deno test --allow-net packages/
• Run a single test file: deno test --allow-net packages/jsr/tests/client.test.ts
• Run development server: deno run --allow-read --allow-write --allow-env --allow-run --allow-net --watch packages/jsr-mcp/mod.ts
• Run production server: deno run --allow-read --allow-write --allow-env --allow-run --allow-net packages/jsr-mcp/mod.ts
• Build MCP server binary: cd packages/jsr-mcp && deno compile --allow-read --allow-write --allow-env --allow-run --allow-net --output=jsr-mcp mod.ts

Git hooks (managed via deno-task-hooks):

• Install hooks: deno task hooks:install
• Pre-commit: Runs deno check, deno fmt --check, and deno lint
• Pre-push: Runs deno publish --dry-run --allow-dirty

Architecture

JSR Client Package (packages/jsr/)

• Purpose: Reusable TypeScript client for the JSR API
• Main exports: mod.ts exports all client functions and types
• Dependencies: Only zod for schema validation
• Can be used independently of the MCP server
• Testing: Uses jsr:@std/assert for assertions

MCP Server Package (packages/jsr-mcp/)

• Purpose: MCP server that exposes JSR functionality to AI assistants
• Dependencies:
  • Local: @wyattjoh/jsr (the client package, imported via relative path)
  • External: @modelcontextprotocol/sdk, @std/dotenv, zod
• Pattern: Uses inline server.tool() calls for MCP tool definitions
• Configuration: Via environment variables (JSR_API_URL, JSR_REGISTRY_URL, JSR_API_TOKEN)

Key Design Patterns

• Workspace imports: The MCP server imports the JSR client using a relative path configured in workspace root
• Type safety: All API interactions use Zod schemas for validation
• Error handling: Consistent error wrapping and reporting
• Testing: Each package has its own test suite using Deno's built-in test runner
• MCP tools: Defined inline using server.tool() with Zod schemas that mirror the JSR client types

Repository Management

• Always run deno fmt, deno lint, and deno check packages/jsr/mod.ts packages/jsr-mcp/mod.ts after modifying code
• Run deno test --allow-net packages/ to verify all tests pass
• When updating tool definitions in the MCP server, ensure schemas match the JSR client types
• The JSR client package can be published independently to JSR for reuse in other projects

Publishing

Each package can be published separately to JSR:

• packages/jsr/ as @wyattjoh/jsr
• packages/jsr-mcp/ as @wyattjoh/jsr-mcp

Both packages include their own LICENSE file and are configured for JSR publishing via deno publish.

JSR MCP

A Deno monorepo containing packages for JSR (JavaScript Registry) access:

• @wyattjoh/jsr - Core library for JSR API access
• @wyattjoh/jsr-mcp - Model Context Protocol (MCP) server for LLM integration

Features

• Search packages across the JSR registry
• Get package details, versions, and dependencies
• Manage scopes and package publishing
• Handle member invitations and permissions
• Access registry statistics and metadata
• Full authentication support for write operations

Requirements

• Deno 2.x or later
• Network access to JSR API
• JSR API token for authenticated operations (optional)

Packages

@wyattjoh/jsr

Core library for accessing JSR API:

deno add @wyattjoh/jsr

import { getPackage, searchPackages } from "@wyattjoh/jsr";

const results = await searchPackages({ query: "react" });
const pkg = await getPackage("deno", "std");

See full documentation

@wyattjoh/jsr-mcp

MCP server for LLM integration:

# Run directly from JSR
deno run --allow-net --allow-env jsr:@wyattjoh/jsr-mcp

# Or install globally
deno install --global --allow-net --allow-env -n jsr-mcp jsr:@wyattjoh/jsr-mcp

For Claude Desktop app integration, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "jsr": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-env",
        "jsr:@wyattjoh/jsr-mcp"
      ],
      "env": {
        "JSR_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Option 2: From Source

1. Clone this repository
2. Install dependencies:

   deno cache packages/*/mod.ts
   

3. Run the server:

   deno run --allow-net --allow-env packages/jsr-mcp/mod.ts
   

Available Tools

The MCP server provides 40 tools for comprehensive JSR access:

Package Operations

• jsr_search_packages - Search for packages
• jsr_get_package - Get package details
• jsr_get_package_version - Get specific version details
• jsr_list_package_versions - List all versions
• jsr_get_package_metadata - Get package metadata
• jsr_get_package_dependencies - Get dependencies
• jsr_get_package_score - Get package quality score
• jsr_get_package_dependents - Find dependent packages
• jsr_create_package - Create new package (requires auth)
• jsr_update_package - Update package (requires auth)
• jsr_delete_package - Delete package (requires auth)

Package Version Management

• jsr_create_package_version - Upload new version (requires auth)
• jsr_update_package_version - Update version, e.g., yank (requires auth)

Scope Management

• jsr_get_scope - Get scope details
• jsr_list_scope_packages - List packages in a scope
• jsr_create_scope - Create new scope (requires auth)
• jsr_update_scope - Update scope settings (requires auth)
• jsr_delete_scope - Delete scope (requires auth)

Member Management

• jsr_list_scope_members - List scope members
• jsr_add_scope_member - Invite member (requires auth)
• jsr_update_scope_member - Update member role (requires auth)
• jsr_remove_scope_member - Remove member (requires auth)
• jsr_list_scope_invites - List pending invites
• jsr_delete_scope_invite - Delete scope invite (requires auth)
• jsr_accept_scope_invite - Accept invite (requires auth)
• jsr_decline_scope_invite - Decline invite (requires auth)

User Operations

• jsr_get_current_user - Get authenticated user
• jsr_get_current_user_scopes - Get user's scopes
• jsr_get_current_user_scope_member - Get user's membership in a scope
• jsr_get_current_user_invites - Get user's pending invites
• jsr_get_user - Get user details
• jsr_get_user_scopes - Get user's scopes

Registry Operations

• jsr_list_packages - List all registry packages
• jsr_get_stats - Get registry statistics

Authorization (OAuth)

• jsr_create_authorization - Start authorization flow (requires auth)
• jsr_get_authorization_details - Get authorization details
• jsr_approve_authorization - Approve authorization (requires auth)
• jsr_deny_authorization - Deny authorization (requires auth)
• jsr_exchange_authorization - Exchange code for token (requires auth)

Publishing

• jsr_get_publishing_task - Get publishing task status

Example Usage

// Search for packages
jsr_search_packages({ query: "react", limit: 10 });

// Get package details
jsr_get_package({ scope: "deno", name: "std" });

// List versions with pagination
jsr_list_package_versions({
  scope: "deno",
  name: "std",
  limit: 20,
  page: 1,
});

// Get dependencies for a specific version
jsr_get_package_dependencies({
  scope: "deno",
  name: "std",
  version: "1.0.0",
});

// Create a new scope (requires authentication)
jsr_create_scope({
  scope: "my-org",
  description: "My organization's packages",
});

Security Notes

• Read operations do not require authentication
• Write operations require a valid JSR API token
• The server only accesses the JSR API endpoints
• No local file system access beyond reading environment variables

Development

This is a Deno workspace monorepo. All commands run from the root affect all packages.

# Clone the repository
git clone https://github.com/wyattjoh/jsr-mcp.git
cd jsr-mcp

# Cache dependencies
deno cache packages/*/mod.ts

# Format all code
deno fmt

# Lint all packages
deno lint

# Type check all packages
deno check packages/jsr/mod.ts packages/jsr-mcp/mod.ts

# Run tests
deno test --allow-net packages/

# Run MCP server locally (with watch mode)
deno run --allow-read --allow-write --allow-env --allow-run --allow-net --watch packages/jsr-mcp/mod.ts

# Run MCP server in production
deno run --allow-read --allow-write --allow-env --allow-run --allow-net packages/jsr-mcp/mod.ts

# Build binary
cd packages/jsr-mcp
deno compile --allow-read --allow-write --allow-env --allow-run --allow-net --output=jsr-mcp mod.ts

# Publish packages (CI/CD)
deno publish

Working on Individual Packages

# Work on @wyattjoh/jsr
cd packages/jsr
deno test --allow-net

# Work on @wyattjoh/jsr-mcp
cd packages/jsr-mcp
deno run --allow-net --allow-env mod.ts

License

MIT