diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c2db872 --- /dev/null +++ b/AGENTS.md @@ -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 --append true --prompt "Assigned to claude-squad session-"` +4. **Set In Progress**: Use `mcp__task-master__set_task_status --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 ` 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 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 # 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 --status completed` +6. **Document Integration**: Update task with merge notes using `mcp__task-master__update_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**: - 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 diff --git a/CLAUDE.md b/CLAUDE.md index e46e928..c1fef24 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) diff --git a/docs/features/configuration-mode/AGENTS.md b/docs/features/configuration-mode/AGENTS.md new file mode 100644 index 0000000..aefaef6 --- /dev/null +++ b/docs/features/configuration-mode/AGENTS.md @@ -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. diff --git a/docs/features/configuration-mode/CLAUDE.md b/docs/features/configuration-mode/CLAUDE.md index 5026bce..e5640f0 100644 --- a/docs/features/configuration-mode/CLAUDE.md +++ b/docs/features/configuration-mode/CLAUDE.md @@ -4,6 +4,14 @@ 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 diff --git a/scripts/sync-claude-agents.js b/scripts/sync-claude-agents.js new file mode 100644 index 0000000..e8d7fe8 --- /dev/null +++ b/scripts/sync-claude-agents.js @@ -0,0 +1,45 @@ +#!/usr/bin/env node +import { promises as fs } from 'fs'; +import path from 'path'; + +async function findClaudeFiles(dir) { + const entries = await fs.readdir(dir, { withFileTypes: true }); + const files = []; + for (const entry of entries) { + const res = path.resolve(dir, entry.name); + if (entry.isDirectory()) { + if (['node_modules', '.git', 'dist'].includes(entry.name)) continue; + files.push(...await findClaudeFiles(res)); + } else if (entry.isFile() && entry.name === 'CLAUDE.md') { + files.push(res); + } + } + return files; +} + +function buildAgentsContent(claudeContent, existing) { + const marker = '## CLAUDE Source'; + const trimmed = claudeContent.trim(); + if (existing && existing.includes(marker)) { + const before = existing.split(marker)[0]; + return `${before}${marker}\n\n${trimmed}\n`; + } + return `${trimmed}\n`; +} + +async function sync() { + const root = process.cwd(); + const claudeFiles = await findClaudeFiles(root); + await Promise.all(claudeFiles.map(async (file) => { + const claudeContent = await fs.readFile(file, 'utf-8'); + const dir = path.dirname(file); + const agentsPath = path.join(dir, 'AGENTS.md'); + let existing = ''; + try { existing = await fs.readFile(agentsPath, 'utf-8'); } catch {} + const updated = buildAgentsContent(claudeContent, existing); + await fs.writeFile(agentsPath, updated, 'utf-8'); + })); + console.log(`Synced ${claudeFiles.length} CLAUDE.md file(s) to AGENTS.md`); +} + +sync().catch(err => { console.error(err); process.exit(1); }); diff --git a/src/commands/AGENTS.md b/src/commands/AGENTS.md new file mode 100644 index 0000000..0cc1794 --- /dev/null +++ b/src/commands/AGENTS.md @@ -0,0 +1,20 @@ +# Commands Module + +## Purpose +Provides CLI subcommands such as `setup`, `extensions`, and `toolset`. + +## Architecture +```mermaid +graph TD + CLI --> Commands + Commands --> Router +``` + +## Delegate +Spawned by the Commander program in `src/index.ts` which delegates to these handlers. + +## Example +```ts +import { main as extensions } from './extensions/main.js'; +await extensions(['install', 'sample']); +``` diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md new file mode 100644 index 0000000..0cc1794 --- /dev/null +++ b/src/commands/CLAUDE.md @@ -0,0 +1,20 @@ +# Commands Module + +## Purpose +Provides CLI subcommands such as `setup`, `extensions`, and `toolset`. + +## Architecture +```mermaid +graph TD + CLI --> Commands + Commands --> Router +``` + +## Delegate +Spawned by the Commander program in `src/index.ts` which delegates to these handlers. + +## Example +```ts +import { main as extensions } from './extensions/main.js'; +await extensions(['install', 'sample']); +``` diff --git a/src/config-manager/AGENTS.md b/src/config-manager/AGENTS.md new file mode 100644 index 0000000..29089b4 --- /dev/null +++ b/src/config-manager/AGENTS.md @@ -0,0 +1,21 @@ +# Config Manager Module + +## Purpose +Centralizes reading and writing of HyperTool configuration and manages migrations. + +## Architecture +```mermaid +graph TD + Server --> ConfigManager + ConfigManager --> Config +``` + +## Delegate +Invoked by CLI utilities like `hypertool-mcp config` to adjust settings. + +## Example +```ts +import { ConfigurationManager } from './index.js'; +const manager = new ConfigurationManager(); +await manager.loadMainConfig(); +``` diff --git a/src/config-manager/CLAUDE.md b/src/config-manager/CLAUDE.md new file mode 100644 index 0000000..29089b4 --- /dev/null +++ b/src/config-manager/CLAUDE.md @@ -0,0 +1,21 @@ +# Config Manager Module + +## Purpose +Centralizes reading and writing of HyperTool configuration and manages migrations. + +## Architecture +```mermaid +graph TD + Server --> ConfigManager + ConfigManager --> Config +``` + +## Delegate +Invoked by CLI utilities like `hypertool-mcp config` to adjust settings. + +## Example +```ts +import { ConfigurationManager } from './index.js'; +const manager = new ConfigurationManager(); +await manager.loadMainConfig(); +``` diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md new file mode 100644 index 0000000..489d320 --- /dev/null +++ b/src/config/AGENTS.md @@ -0,0 +1,20 @@ +# Config Module + +## Purpose +Loads and validates server and extension configuration from files or preferences. + +## Architecture +```mermaid +graph TD + ConfigFile --> Config + Config --> ConfigManager +``` + +## Delegate +Used by server startup and the configuration manager to discover and parse `mcp.json`. + +## Example +```ts +import { discoverMcpConfig } from './mcpConfigLoader.js'; +const config = await discoverMcpConfig(); +``` diff --git a/src/config/CLAUDE.md b/src/config/CLAUDE.md new file mode 100644 index 0000000..489d320 --- /dev/null +++ b/src/config/CLAUDE.md @@ -0,0 +1,20 @@ +# Config Module + +## Purpose +Loads and validates server and extension configuration from files or preferences. + +## Architecture +```mermaid +graph TD + ConfigFile --> Config + Config --> ConfigManager +``` + +## Delegate +Used by server startup and the configuration manager to discover and parse `mcp.json`. + +## Example +```ts +import { discoverMcpConfig } from './mcpConfigLoader.js'; +const config = await discoverMcpConfig(); +``` diff --git a/src/connection/AGENTS.md b/src/connection/AGENTS.md new file mode 100644 index 0000000..2b38578 --- /dev/null +++ b/src/connection/AGENTS.md @@ -0,0 +1,21 @@ +# Connection Module + +## Purpose +Maintains client connections and pooling to underlying MCP servers and monitors health. + +## Architecture +```mermaid +graph TD + Server --> ConnectionManager + ConnectionManager --> MCPServer +``` + +## Delegate +The server instantiates `ConnectionManager` to spawn and manage connections. + +## Example +```ts +import { ConnectionManager } from './manager.js'; +const manager = new ConnectionManager(); +await manager.addServer(serverConfig); +``` diff --git a/src/connection/CLAUDE.md b/src/connection/CLAUDE.md new file mode 100644 index 0000000..2b38578 --- /dev/null +++ b/src/connection/CLAUDE.md @@ -0,0 +1,21 @@ +# Connection Module + +## Purpose +Maintains client connections and pooling to underlying MCP servers and monitors health. + +## Architecture +```mermaid +graph TD + Server --> ConnectionManager + ConnectionManager --> MCPServer +``` + +## Delegate +The server instantiates `ConnectionManager` to spawn and manage connections. + +## Example +```ts +import { ConnectionManager } from './manager.js'; +const manager = new ConnectionManager(); +await manager.addServer(serverConfig); +``` diff --git a/src/db/AGENTS.md b/src/db/AGENTS.md new file mode 100644 index 0000000..3f6af5b --- /dev/null +++ b/src/db/AGENTS.md @@ -0,0 +1,20 @@ +# Database Module + +## Purpose +Provides file-backed storage services for server configuration and metadata. + +## Architecture +```mermaid +graph TD + Server --> Database +``` + +## Delegate +Configuration loaders and managers call the composite database service when persisting data. + +## Example +```ts +import { CompositeDatabaseService } from './compositeDatabaseService.js'; +const db = new CompositeDatabaseService(); +await db.init(); +``` diff --git a/src/db/CLAUDE.md b/src/db/CLAUDE.md new file mode 100644 index 0000000..3f6af5b --- /dev/null +++ b/src/db/CLAUDE.md @@ -0,0 +1,20 @@ +# Database Module + +## Purpose +Provides file-backed storage services for server configuration and metadata. + +## Architecture +```mermaid +graph TD + Server --> Database +``` + +## Delegate +Configuration loaders and managers call the composite database service when persisting data. + +## Example +```ts +import { CompositeDatabaseService } from './compositeDatabaseService.js'; +const db = new CompositeDatabaseService(); +await db.init(); +``` diff --git a/src/discovery/AGENTS.md b/src/discovery/AGENTS.md new file mode 100644 index 0000000..9913ca6 --- /dev/null +++ b/src/discovery/AGENTS.md @@ -0,0 +1,21 @@ +# Discovery Module + +## Purpose +Discovers available tools from connected MCP servers and caches metadata. + +## Architecture +```mermaid +graph TD + Server --> Discovery + Discovery --> Connection +``` + +## Delegate +The request router uses `ToolDiscoveryEngine` to look up tools before routing calls. + +## Example +```ts +import { ToolDiscoveryEngine } from './service.js'; +const engine = new ToolDiscoveryEngine(manager); +await engine.initialize(); +``` diff --git a/src/discovery/CLAUDE.md b/src/discovery/CLAUDE.md new file mode 100644 index 0000000..9913ca6 --- /dev/null +++ b/src/discovery/CLAUDE.md @@ -0,0 +1,21 @@ +# Discovery Module + +## Purpose +Discovers available tools from connected MCP servers and caches metadata. + +## Architecture +```mermaid +graph TD + Server --> Discovery + Discovery --> Connection +``` + +## Delegate +The request router uses `ToolDiscoveryEngine` to look up tools before routing calls. + +## Example +```ts +import { ToolDiscoveryEngine } from './service.js'; +const engine = new ToolDiscoveryEngine(manager); +await engine.initialize(); +``` diff --git a/src/dxt/AGENTS.md b/src/dxt/AGENTS.md new file mode 100644 index 0000000..2094494 --- /dev/null +++ b/src/dxt/AGENTS.md @@ -0,0 +1,20 @@ +# DXT Module + +## Purpose +Loads and extracts DXT packages and reads their manifests. + +## Architecture +```mermaid +graph TD + Server --> DXT + DXT --> Package +``` + +## Delegate +Feature flag or setup routines call the loader when enabling a DXT package. + +## Example +```ts +import { loadDxt } from './loader.js'; +const { manifest } = await loadDxt('path/to/package.zip'); +``` diff --git a/src/dxt/CLAUDE.md b/src/dxt/CLAUDE.md new file mode 100644 index 0000000..2094494 --- /dev/null +++ b/src/dxt/CLAUDE.md @@ -0,0 +1,20 @@ +# DXT Module + +## Purpose +Loads and extracts DXT packages and reads their manifests. + +## Architecture +```mermaid +graph TD + Server --> DXT + DXT --> Package +``` + +## Delegate +Feature flag or setup routines call the loader when enabling a DXT package. + +## Example +```ts +import { loadDxt } from './loader.js'; +const { manifest } = await loadDxt('path/to/package.zip'); +``` diff --git a/src/errors/AGENTS.md b/src/errors/AGENTS.md new file mode 100644 index 0000000..6e87110 --- /dev/null +++ b/src/errors/AGENTS.md @@ -0,0 +1,19 @@ +# Errors Module + +## Purpose +Defines reusable error classes and recovery helpers for consistent failure handling. + +## Architecture +```mermaid +graph TD + Modules --> Errors +``` + +## Delegate +Called throughout the server and router to construct typed errors. + +## Example +```ts +import { ConfigurationError } from './index.js'; +throw new ConfigurationError('Missing field'); +``` diff --git a/src/errors/CLAUDE.md b/src/errors/CLAUDE.md new file mode 100644 index 0000000..6e87110 --- /dev/null +++ b/src/errors/CLAUDE.md @@ -0,0 +1,19 @@ +# Errors Module + +## Purpose +Defines reusable error classes and recovery helpers for consistent failure handling. + +## Architecture +```mermaid +graph TD + Modules --> Errors +``` + +## Delegate +Called throughout the server and router to construct typed errors. + +## Example +```ts +import { ConfigurationError } from './index.js'; +throw new ConfigurationError('Missing field'); +``` diff --git a/src/extensions/AGENTS.md b/src/extensions/AGENTS.md new file mode 100644 index 0000000..810f0fa --- /dev/null +++ b/src/extensions/AGENTS.md @@ -0,0 +1,21 @@ +# Extensions Module + +## Purpose +Discovers, validates, and manages runtime configuration for extensions. + +## Architecture +```mermaid +graph TD + Server --> ExtensionManager + ExtensionManager --> Extension +``` + +## Delegate +The extension CLI commands and server startup use `ExtensionManager` to load extensions. + +## Example +```ts +import { ExtensionManager } from './manager.js'; +const manager = new ExtensionManager(); +await manager.initialize(); +``` diff --git a/src/extensions/CLAUDE.md b/src/extensions/CLAUDE.md new file mode 100644 index 0000000..810f0fa --- /dev/null +++ b/src/extensions/CLAUDE.md @@ -0,0 +1,21 @@ +# Extensions Module + +## Purpose +Discovers, validates, and manages runtime configuration for extensions. + +## Architecture +```mermaid +graph TD + Server --> ExtensionManager + ExtensionManager --> Extension +``` + +## Delegate +The extension CLI commands and server startup use `ExtensionManager` to load extensions. + +## Example +```ts +import { ExtensionManager } from './manager.js'; +const manager = new ExtensionManager(); +await manager.initialize(); +``` diff --git a/src/integration/AGENTS.md b/src/integration/AGENTS.md new file mode 100644 index 0000000..d2e5225 --- /dev/null +++ b/src/integration/AGENTS.md @@ -0,0 +1,20 @@ +# Integration Tests Module + +## Purpose +Contains end-to-end tests verifying HTTP, stdio, and CLI integrations. + +## Architecture +```mermaid +graph TD + Tests --> Integration + Integration --> Server +``` + +## Delegate +Executed by the test runner via `npm test` to ensure components work together. + +## Example +```ts +// run a specific integration test +npm test src/integration/stdio-transport.test.ts +``` diff --git a/src/integration/CLAUDE.md b/src/integration/CLAUDE.md new file mode 100644 index 0000000..d2e5225 --- /dev/null +++ b/src/integration/CLAUDE.md @@ -0,0 +1,20 @@ +# Integration Tests Module + +## Purpose +Contains end-to-end tests verifying HTTP, stdio, and CLI integrations. + +## Architecture +```mermaid +graph TD + Tests --> Integration + Integration --> Server +``` + +## Delegate +Executed by the test runner via `npm test` to ensure components work together. + +## Example +```ts +// run a specific integration test +npm test src/integration/stdio-transport.test.ts +``` diff --git a/src/mcp-manager/AGENTS.md b/src/mcp-manager/AGENTS.md new file mode 100644 index 0000000..a251ffd --- /dev/null +++ b/src/mcp-manager/AGENTS.md @@ -0,0 +1,21 @@ +# MCP Manager Module + +## Purpose +Reads and updates the user's `mcp.json` to register available MCP servers. + +## Architecture +```mermaid +graph TD + Server --> MCPManager + MCPManager --> ConnectionManager +``` + +## Delegate +CLI service commands call `MCPServerManager` to add or remove server entries. + +## Example +```ts +import { MCPServerManager } from './index.js'; +const mgr = new MCPServerManager(); +await mgr.initialize(); +``` diff --git a/src/mcp-manager/CLAUDE.md b/src/mcp-manager/CLAUDE.md new file mode 100644 index 0000000..a251ffd --- /dev/null +++ b/src/mcp-manager/CLAUDE.md @@ -0,0 +1,21 @@ +# MCP Manager Module + +## Purpose +Reads and updates the user's `mcp.json` to register available MCP servers. + +## Architecture +```mermaid +graph TD + Server --> MCPManager + MCPManager --> ConnectionManager +``` + +## Delegate +CLI service commands call `MCPServerManager` to add or remove server entries. + +## Example +```ts +import { MCPServerManager } from './index.js'; +const mgr = new MCPServerManager(); +await mgr.initialize(); +``` diff --git a/src/router/AGENTS.md b/src/router/AGENTS.md new file mode 100644 index 0000000..cbceb95 --- /dev/null +++ b/src/router/AGENTS.md @@ -0,0 +1,21 @@ +# Router Module + +## Purpose +Routes tool invocations to the correct underlying MCP server and tracks stats. + +## Architecture +```mermaid +graph TD + Server --> Router + Router --> Connection +``` + +## Delegate +`MetaMCPServer` creates a `RequestRouter` instance that consults discovery and connection managers. + +## Example +```ts +import { RequestRouter } from './router.js'; +const router = new RequestRouter(discovery, connections); +const result = await router.route(callRequest); +``` diff --git a/src/router/CLAUDE.md b/src/router/CLAUDE.md new file mode 100644 index 0000000..cbceb95 --- /dev/null +++ b/src/router/CLAUDE.md @@ -0,0 +1,21 @@ +# Router Module + +## Purpose +Routes tool invocations to the correct underlying MCP server and tracks stats. + +## Architecture +```mermaid +graph TD + Server --> Router + Router --> Connection +``` + +## Delegate +`MetaMCPServer` creates a `RequestRouter` instance that consults discovery and connection managers. + +## Example +```ts +import { RequestRouter } from './router.js'; +const router = new RequestRouter(discovery, connections); +const result = await router.route(callRequest); +``` diff --git a/src/scripts/AGENTS.md b/src/scripts/AGENTS.md new file mode 100644 index 0000000..91521e5 --- /dev/null +++ b/src/scripts/AGENTS.md @@ -0,0 +1,20 @@ +# Scripts Module + +## Purpose +Houses setup routines for integrating HyperTool with environments like Cursor or Claude Desktop. + +## Architecture +```mermaid +graph TD + Developer --> Scripts + Scripts --> Environment +``` + +## Delegate +The CLI `setup` command loads these scripts to perform installations. + +## Example +```ts +import { CursorSetup } from './cursor/setup.js'; +await new CursorSetup().run(false); +``` diff --git a/src/scripts/CLAUDE.md b/src/scripts/CLAUDE.md new file mode 100644 index 0000000..91521e5 --- /dev/null +++ b/src/scripts/CLAUDE.md @@ -0,0 +1,20 @@ +# Scripts Module + +## Purpose +Houses setup routines for integrating HyperTool with environments like Cursor or Claude Desktop. + +## Architecture +```mermaid +graph TD + Developer --> Scripts + Scripts --> Environment +``` + +## Delegate +The CLI `setup` command loads these scripts to perform installations. + +## Example +```ts +import { CursorSetup } from './cursor/setup.js'; +await new CursorSetup().run(false); +``` diff --git a/src/server/AGENTS.md b/src/server/AGENTS.md new file mode 100644 index 0000000..078f44f --- /dev/null +++ b/src/server/AGENTS.md @@ -0,0 +1,23 @@ +# Server Module + +## Purpose +Implements the Meta MCP server classes, HTTP interfaces, and tooling exposure. + +## Architecture +```mermaid +graph TD + Client --> Server + Server --> Router + Server --> Connection + Server --> Discovery +``` + +## Delegate +`index.ts` bootstraps `MetaMCPServer` or `EnhancedMetaMCPServer` based on runtime options. + +## Example +```ts +import { MetaMCPServerFactory } from './factory.js'; +const server = await MetaMCPServerFactory.create(config); +await server.start(); +``` diff --git a/src/server/CLAUDE.md b/src/server/CLAUDE.md new file mode 100644 index 0000000..078f44f --- /dev/null +++ b/src/server/CLAUDE.md @@ -0,0 +1,23 @@ +# Server Module + +## Purpose +Implements the Meta MCP server classes, HTTP interfaces, and tooling exposure. + +## Architecture +```mermaid +graph TD + Client --> Server + Server --> Router + Server --> Connection + Server --> Discovery +``` + +## Delegate +`index.ts` bootstraps `MetaMCPServer` or `EnhancedMetaMCPServer` based on runtime options. + +## Example +```ts +import { MetaMCPServerFactory } from './factory.js'; +const server = await MetaMCPServerFactory.create(config); +await server.start(); +``` diff --git a/src/types/AGENTS.md b/src/types/AGENTS.md new file mode 100644 index 0000000..1179536 --- /dev/null +++ b/src/types/AGENTS.md @@ -0,0 +1,19 @@ +# Types Module + +## Purpose +Holds shared TypeScript definitions for runtime and configuration structures. + +## Architecture +```mermaid +graph TD + Modules --> Types +``` + +## Delegate +Imported by most modules to ensure consistent typing. + +## Example +```ts +import { RuntimeOptions } from './runtime.js'; +function init(opts: RuntimeOptions) {} +``` diff --git a/src/types/CLAUDE.md b/src/types/CLAUDE.md new file mode 100644 index 0000000..1179536 --- /dev/null +++ b/src/types/CLAUDE.md @@ -0,0 +1,19 @@ +# Types Module + +## Purpose +Holds shared TypeScript definitions for runtime and configuration structures. + +## Architecture +```mermaid +graph TD + Modules --> Types +``` + +## Delegate +Imported by most modules to ensure consistent typing. + +## Example +```ts +import { RuntimeOptions } from './runtime.js'; +function init(opts: RuntimeOptions) {} +``` diff --git a/src/utils/AGENTS.md b/src/utils/AGENTS.md new file mode 100644 index 0000000..7ce065d --- /dev/null +++ b/src/utils/AGENTS.md @@ -0,0 +1,20 @@ +# Utils Module + +## Purpose +Provides helper utilities for logging, theming, environment parsing, and path helpers. + +## Architecture +```mermaid +graph TD + Modules --> Utils +``` + +## Delegate +Used across the codebase; for example the logger is spawned by `index.ts` during boot. + +## Example +```ts +import { createChildLogger } from './logging.js'; +const log = createChildLogger({ module: 'demo' }); +log.info('started'); +``` diff --git a/src/utils/CLAUDE.md b/src/utils/CLAUDE.md new file mode 100644 index 0000000..7ce065d --- /dev/null +++ b/src/utils/CLAUDE.md @@ -0,0 +1,20 @@ +# Utils Module + +## Purpose +Provides helper utilities for logging, theming, environment parsing, and path helpers. + +## Architecture +```mermaid +graph TD + Modules --> Utils +``` + +## Delegate +Used across the codebase; for example the logger is spawned by `index.ts` during boot. + +## Example +```ts +import { createChildLogger } from './logging.js'; +const log = createChildLogger({ module: 'demo' }); +log.info('started'); +```