Skip to content

CLAUDE.md

Latest commit

 

History

History
156 lines (119 loc) · 7.57 KB

CLAUDE.md

File metadata and controls

156 lines (119 loc) · 7.57 KB
Raw

hypertool-mcp Development Instructions

For Agents Working on This Project

You are working on hypertool-mcp: a TypeScript MCP proxy server that routes requests between clients and multiple underlying MCP servers.

📋 Essential Reading

READ FIRST: .taskmaster/docs/prd.txt - Contains complete project requirements, architecture, and technical specifications.

🎯 High-Level Goal

Build a single MCP server that:

  1. Connects to multiple underlying MCP servers as a client
  2. Discovers available tools from those servers
  3. Exposes a configurable subset of those tools to its own clients
  4. Routes tool calls transparently to the correct underlying server

Simple Example: If server A has tools (foo, bar) and server B has tools (bam, bee), this proxy can expose just (foo, bam) and route calls accordingly.

🏗️ Agent Instructions

Creating PRDs (Product Requirement Documents)

When creating new PRDs for features, bugs, or improvements:

  1. Use the PRD Template: Copy docs/prd-template.md as your starting point
  2. Fill in Metadata: Always populate the metadata section at the top:
    • Use git log -1 --format="%H" to get the reference commit
    • Use git branch --show-current to get the current branch
    • Set appropriate priority (P0-P3) based on impact
  3. Save PRDs in Correct Location:
    • Bug PRDs: docs/bugs/[bug-name].md
    • Feature PRDs: docs/features/[feature-name].md
    • General PRDs: docs/[prd-name].md
  4. Keep PRDs Updated: Update status and revision history as work progresses

Before Starting Any Task

Step 1: Get Your Task Assignment

  • If TASK_ID environment variable is set, use that task ID
  • If not set, you need to claim an available task using this process:
  1. Find Available Tasks: Use mcp__task-master__get_tasks --status pending to see unassigned tasks
  2. Claim a Task: Look for tasks whose details DON'T contain "Assigned to claude-squad"
  3. Mark Assignment: Use mcp__task-master__update_task --id <task-id> --append true --prompt "Assigned to claude-squad session-<unique-id>"
  4. Set In Progress: Use mcp__task-master__set_task_status --id <task-id> --status in-progress

Step 2: Get Full Context

  1. Read the Main PRD: Check .taskmaster/docs/prd.txt for complete project context
  2. Get Task Details: Use mcp__task-master__get_task --id <your-task-id> to see your specific requirements
  3. Find Task-Specific PRD: Look in both locations for PRDs related to your task:
    • Primary location: docs/ directory (bugs, features, etc.)
    • Legacy location: .taskmaster/docs/ directory
    • Task 29: prd.cursor.txt - Cursor IDE integration
    • Task 30: prd.bin.txt - NPM publishing workflow
    • Task 31: prd.claude-code.txt - Claude Code integration
    • Task 32: prd.claude-desktop.txt - Claude Desktop integration
    • Bug PRDs: docs/bugs/ - Bug fix specifications
    • Feature PRDs: docs/features/ - New feature specifications
  4. Review Dependencies: Understand which tasks must complete before yours
  5. Study Reference: Look at https://github.com/toolprint/cco-mcp for TypeScript MCP patterns

Development Standards

  • Language: TypeScript only with full type safety
  • Transports: Support both stdio and HTTP/SSE
  • Testing: Write tests for your components using Jest
  • Error Handling: Graceful failures with clear messages
  • Logging: Use structured logging for debugging
  • Dependencies: Use npm/yarn for package management
  • Code Quality: Follow ESLint/Prettier standards from justfile

Key Patterns to Follow

  • Study cco-mcp repository for MCP server best practices
  • Use proper TypeScript interfaces for all MCP protocol types
  • Implement connection pooling for multiple server connections
  • Cache tool definitions but handle real-time updates
  • Route requests without modifying their structure

Project Structure

Create your code in logical directories under src/:

  • src/server/ - Core MCP server implementation
  • src/config/ - Configuration parsing and validation
  • src/connection/ - Connection management and pooling
  • src/discovery/ - Tool discovery and caching
  • src/router/ - Request routing logic
  • src/types/ - TypeScript type definitions
  • src/scripts/ - Setup scripts for integration (Cursor, Claude Code, Claude Desktop)

When You're Done

  1. Run PR Preparation Checks:

    • ALWAYS run just pr-prep before committing - This runs ALL the checks from the GitHub PR validation workflow
    • This includes: pre-commit hooks, build, tests (CI reporter), type checking, linting, and format checking
    • If just pr-prep fails, fix the issues before committing
    • This ensures your branch will pass CI checks when merged

  2. Merge Latest Changes: Before finalizing, merge the latest changes from your base branch to avoid conflicts:

    # Find your base branch (usually integration, cs-setup, or main)
git log --oneline --graph | head -10  # Look for where your branch diverged
git merge <base-branch-name>  # e.g., git merge integration

# IMPORTANT: All branches are LOCAL only - never pull from origin
# Your base branch is always a local branch, not a remote one

  3. Commit Your Work: Create clear commit messages describing your implementation

  4. Mark Task Complete: Use mcp__task-master__set_task_status --id <your-task-id> --status completed

  5. Document Integration: Update task with merge notes using mcp__task-master__update_task --id <your-task-id> --append --prompt "Work completed in local branch [branch-name]. Merged latest changes from [base-branch]. Ready for local merge. Integration notes: [any important details]"

  6. Keep Work Local: Do NOT push branches to remote - all work stays in local worktrees for manual integration

Example Task Assignment Workflow

# Check if task assigned via environment
if TASK_ID is set:
  - Use that task ID
else:
  - Call mcp__task-master__get_tasks --status pending
  - Find first task where details doesn't contain "Assigned to claude-squad"
  - Call mcp__task-master__update_task --id X --append --prompt "Assigned to claude-squad session-$(date +%s)"
  - Call mcp__task-master__set_task_status --id X --status in-progress

# Then proceed with development work

🔗 Quick References

  • Main PRD: .taskmaster/docs/prd.txt - Complete project requirements
  • PRD Template: docs/prd-template.md - Template for new PRDs
  • Bug PRDs: docs/bugs/ - Bug fix specifications
  • Feature PRDs: docs/features/ - New feature specifications
  • Task-Specific PRDs: .taskmaster/docs/ - Legacy task-specific PRDs
  • Tasks: Use Task Master MCP tools to view your specific task
  • Reference: https://github.com/toolprint/cco-mcp - TypeScript MCP patterns
  • Example Config: .mcp.json - Shows target server types to support
  • Build Tools: justfile - Available commands for build/test/lint
  • Integration Testing: src/server/tools/config-tools/CLAUDE.md - Tool behavior testing for persona and non-persona modes
  • Integration: Work stays in local worktrees, merges into current feature branch

⚠️ Important Reminders

  • NO remote pushing - keep all work local until manual integration
  • NO pulling from origin - all branches (main, integration, etc.) are LOCAL only
  • Follow dependencies - check which tasks must complete before yours
  • Test thoroughly - your component will be integrated with others
  • Document integration points - help future tasks understand your interfaces
  • Local-only workflow - never use git pull, git fetch, or push to remote