Skip to content

docs: add module diagrams and remove markers #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add module diagrams and remove markers #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 195 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
# hypertool-mcp Agent Instructions

This repository uses `AGENTS.md` files derived from corresponding `CLAUDE.md` documents.

## Subdirectory Links
- [Configuration Mode Feature](docs/features/configuration-mode/AGENTS.md)
- [Commands Module](src/commands/AGENTS.md)
- [Config Module](src/config/AGENTS.md)
- [Config Manager Module](src/config-manager/AGENTS.md)
- [Connection Module](src/connection/AGENTS.md)
- [Database Module](src/db/AGENTS.md)
- [Discovery Module](src/discovery/AGENTS.md)
- [DXT Module](src/dxt/AGENTS.md)
- [Errors Module](src/errors/AGENTS.md)
- [Extensions Module](src/extensions/AGENTS.md)
- [Integration Tests Module](src/integration/AGENTS.md)
- [MCP Manager Module](src/mcp-manager/AGENTS.md)
- [Router Module](src/router/AGENTS.md)
- [Scripts Module](src/scripts/AGENTS.md)
- [Server Module](src/server/AGENTS.md)
- [Types Module](src/types/AGENTS.md)
- [Utils Module](src/utils/AGENTS.md)

## Synchronization Workflow
1. Run `node scripts/sync-claude-agents.js` to regenerate `AGENTS.md` files from their matching `CLAUDE.md` sources.
2. Review the generated `AGENTS.md` files for formatting or manual notes.
3. Commit any changes.

## CLAUDE Source

# 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.

### 🖼️ Architecture

```mermaid
graph TD
Client -->|requests| Proxy
Proxy -->|routes| MCP_A
Proxy -->|routes| MCP_B
```

### 🏗️ 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. **Test Your Implementation**:
- Run ALL tests (`npm test` or `just test`) and verify they pass
- Ensure tests specifically related to your changes are passing
- If you added new functionality, write tests for it and verify they pass
- If you modified existing functionality, ensure existing tests still pass
2. **Run Code Quality**: Use `just lint` and `just format` to ensure code standards
3. **Merge Latest Changes**: Before finalizing, merge the latest changes from your base branch to avoid conflicts:

```bash
# 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
```

4. **Commit Your Work**: Create clear commit messages describing your implementation
5. **Mark Task Complete**: Use `mcp__task-master__set_task_status --id <your-task-id> --status completed`
6. **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]"`
7. **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**: 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
9 changes: 9 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ Build a single MCP server that:

**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.

### 🖼️ Architecture

```mermaid
graph TD
Client -->|requests| Proxy
Proxy -->|routes| MCP_A
Proxy -->|routes| MCP_B
```

### 🏗️ Agent Instructions

#### Creating PRDs (Product Requirement Documents)
Expand Down
180 changes: 180 additions & 0 deletions docs/features/configuration-mode/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
# Configuration Mode Feature - Agent Instructions

## Quick Start for Agents

You are implementing the **Configuration Mode** feature for hypertool-mcp. This feature separates configuration tools from operational tools to reduce cognitive load on AI assistants.

## Architecture
```mermaid
graph TD
User --> ConfigurationMode
ConfigurationMode --> ConfigToolsManager
ConfigurationMode --> ToolsetManager
```

## Essential Reading Order

### 1. Understand the Project Context
1. **Read First**: `/CLAUDE.md` - Project development standards
2. **Read Second**: `/README.md` - Understand what hypertool-mcp does
3. **Read Third**: `./PRD.md` - Complete feature specification

### 2. Understand Current Architecture
Before implementing any task, familiarize yourself with:

#### Key Files to Study
```bash
# Core server implementation
src/server/enhanced.ts # Main server class - you'll modify this
src/server/tools/index.ts # Current tool registration
src/toolset/manager.ts # ToolsetManager - your parallel component

# Tool implementations (for reference)
src/server/tools/equip-toolset.ts
src/server/tools/build-toolset.ts
src/server/tools/list-available-tools.ts

# Type definitions
src/server/tools/types.ts # ToolModule interface
src/types/options.ts # RuntimeOptions interface
```

#### Key Patterns to Understand
1. **Tool Module Pattern**: How tools are defined and registered
2. **Dependency Injection**: How tools receive dependencies
3. **Event System**: How `tools_changed` notifications work
4. **MCP Protocol**: Tool listing and calling conventions

## Task Implementation Guide

### Before Starting Any Task

1. **Check Dependencies**: Review the task's dependencies in `tasks/README.md`
2. **Read Previous Work**: If dependencies exist, understand their implementation
3. **Review Tests**: Look at existing test patterns in the codebase

### For Each Task

#### TASK-001: ConfigToolsManager
**Start Here** - This is the foundation
1. Study `src/toolset/manager.ts` for the pattern to follow
2. Look at how tool modules are structured in `src/server/tools/`
3. Create parallel structure in `src/config-tools/`

#### TASK-002: Mode Switching Tools
1. Reference existing tool implementations in `src/server/tools/`
2. Follow the same module pattern and Zod schema approach
3. These are simple tools with no arguments

#### TASK-003: Server Integration
**Most Complex Task** - Requires careful modification
1. Study entire `src/server/enhanced.ts` file first
2. Understand the current `listTools()` and `callTool()` flow
3. Add mode logic without breaking existing functionality

#### TASK-004: Auto-Exit Triggers
1. Modify existing tool handlers carefully
2. Ensure backward compatibility
3. Only trigger on successful operations

#### TASK-005: Feature Flag
1. Check how other runtime options are handled
2. Ensure flag properly disables all new behavior
3. Default should be new behavior (enabled)

#### TASK-006: Testing
1. Follow existing test patterns in the codebase
2. Mock dependencies appropriately
3. Test both success and failure paths

#### TASK-007: Documentation
1. Match the style of existing documentation
2. Include practical examples
3. Explain both the "what" and "why"

## Common Pitfalls to Avoid

### ❌ Don't Break Existing Functionality
- Always ensure backward compatibility
- Test with existing toolsets
- Verify `tools_changed` notifications still work

### ❌ Don't Forget Edge Cases
- What if no MCP servers are connected?
- What if toolset operations fail?
- What if mode switching is called in wrong mode?

### ❌ Don't Skip Tests
- Write tests as you implement
- Test error conditions
- Test with feature flag both on and off

## Implementation Checklist

Before marking any task complete:

- [ ] Code follows TypeScript best practices
- [ ] All tests pass (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Feature works with flag enabled AND disabled
- [ ] No breaking changes to existing functionality
- [ ] Code is documented with JSDoc comments
- [ ] Integration tested with real MCP client

## Testing Your Implementation

### Manual Testing
```bash
# Build the project
npm run build

# Run with configuration mode (default)
npm start -- --mcp-config .mcp.json

# Run with configuration mode disabled
npm start -- --mcp-config .mcp.json --disable-configuration-mode

# Test with stdio transport
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npm start
```

### Automated Testing
```bash
# Run all tests
npm test

# Run specific test file
npm test -- src/config-tools/manager.test.ts

# Run with coverage
npm test -- --coverage
```

## Getting Help

### Key Concepts
- **MCP (Model Context Protocol)**: The protocol for tool communication
- **Tool Module**: Self-contained tool definition with schema and handler
- **Toolset**: A saved configuration of selected tools
- **Discovery Engine**: Finds tools from downstream MCP servers

### Reference Implementation
The closest reference is the ToolsetManager. Your ConfigToolsManager should follow a similar pattern but for configuration tools instead of discovered tools.

### Architecture Decision
The separation of concerns is key:
- **ToolsetManager**: Manages discovered tools from downstream servers
- **ConfigToolsManager**: Manages built-in configuration tools
- **EnhancedMCPServer**: Routes between them based on mode

## Success Criteria

Your implementation is successful when:
1. Server starts in config mode when no toolset is equipped
2. Mode switching works smoothly via tool calls
3. Auto-exit triggers work on toolset equip
4. Feature flag properly disables the feature
5. All existing tests still pass
6. New tests provide >80% coverage

Remember: The goal is to reduce cognitive load on AI assistants by showing only relevant tools at the right time.
Loading
Loading