{"id":30057009,"url":"https://github.com/zachhandley/zmcptools","last_synced_at":"2025-08-07T23:42:10.372Z","repository":{"id":304421492,"uuid":"1008560583","full_name":"ZachHandley/ZMCPTools","owner":"ZachHandley","description":"A custom TypeScript MCP Server intended to be used with Claude Code","archived":false,"fork":false,"pushed_at":"2025-07-18T18:16:16.000Z","size":2177,"stargazers_count":35,"open_issues_count":1,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T22:43:31.075Z","etag":null,"topics":["claude","claude-ai","claude-code","feature-rich","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZachHandley.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T18:26:16.000Z","updated_at":"2025-07-28T08:41:30.000Z","dependencies_parsed_at":"2025-07-13T02:48:48.223Z","dependency_job_id":null,"html_url":"https://github.com/ZachHandley/ZMCPTools","commit_stats":null,"previous_names":["zachhandley/zmcptools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ZachHandley/ZMCPTools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZachHandley%2FZMCPTools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZachHandley%2FZMCPTools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZachHandley%2FZMCPTools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZachHandley%2FZMCPTools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZachHandley","download_url":"https://codeload.github.com/ZachHandley/ZMCPTools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZachHandley%2FZMCPTools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269342867,"owners_count":24401076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-ai","claude-code","feature-rich","mcp","mcp-server"],"created_at":"2025-08-07T23:42:06.018Z","updated_at":"2025-08-07T23:42:10.323Z","avatar_url":"https://github.com/ZachHandley.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/zachhandley-zmcptools-badge.png)](https://mseep.ai/app/zachhandley-zmcptools)\n\n# ZMCPTools\n\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)\n[![MCP Protocol](https://img.shields.io/badge/MCP-1.15.0-purple.svg)](https://modelcontextprotocol.io/)\n\n🚀 **TypeScript MCP Tools for Claude Code** - Professional multi-agent orchestration platform with 61 enhanced tools, documentation intelligence, and advanced automation capabilities.\n\n## ⚠️ Important Setup Note\n\n**Before spawning agents**, run this command once to enable proper agent permissions:\n```bash\nclaude --dangerously-skip-permissions\n```\nAgents run on daemon threads and need this permission to execute properly.\n\n## ✨ Key Features\n\n### 🎯 **Multi-Agent Orchestration**\n- **Architect-Led Coordination**: AI architect automatically spawns and coordinates specialized agent teams\n- **Intelligent Dependencies**: Agents work in proper order (Backend → Frontend → Testing → Documentation)\n- **Real-Time Communication**: Agents collaborate through dedicated chat rooms with message broadcasting\n- **Foundation Session Caching**: 85-90% cost reduction through automatic shared context management\n- **Professional Task Management**: Create, assign, track, and monitor complex development workflows\n\n### 🎨 **TypeScript-First Architecture** \n- **Type-Safe MCP Server**: Built with Zod schemas and strict TypeScript for reliability\n- **Modern CLI Interface**: Commander.js-powered CLI with structured command hierarchy\n- **Development Ready**: One-command setup with hot-reload development via tsx\n- **Binary Distribution**: Global access via `claude-mcp-tools` and `claude-mcp-server` commands\n- **Professional Build System**: tsup-based compilation with dual CLI/server binaries\n\n### 🌐 **Advanced Browser Automation**\n- **Playwright Integration**: Professional web automation with session management\n- **AI-Powered DOM Analysis**: Intelligent page structure analysis and navigation\n- **Screenshot Analysis**: AI-driven visual page analysis with region focusing\n- **Smart Session Management**: Auto-cleanup, session persistence, and connection pooling\n- **Legacy Support**: Comprehensive tool migration with backward compatibility\n\n### 📚 **Documentation Intelligence \u0026 Vector Search**\n- **LanceDB Vector Database**: Local, high-performance semantic search with multiple embedding providers\n- **Intelligent Web Scraping**: Multi-page documentation collection with automatic vectorization\n- **Advanced Content Processing**: Smart URL filtering, pattern matching, and content extraction\n- **Job Management**: Background worker system with status monitoring and job control\n- **Documentation Sources**: Track and manage multiple documentation repositories\n\n### 🧠 **Knowledge Graph \u0026 Memory Systems**\n- **Graph-Based Knowledge Storage**: Entity-relationship modeling for cross-agent learning\n- **Semantic Search**: Vector-powered knowledge discovery and relationship traversal\n- **Shared Memory**: Persistent agent collaboration and insight sharing\n- **Project Analysis**: Comprehensive code structure analysis with symbol extraction\n- **Smart File Operations**: Pattern-based file operations with fuzzy matching\n\n## 🚀 Quick Installation\n\n### Prerequisites\n- **Node.js 18+**: Required for TypeScript runtime and LanceDB native bindings  \n- **Claude Code CLI**: [Anthropic's Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)\n- **Package Manager**: npm (included), yarn, pnpm, or bun\n\n### Production Installation (Recommended)\n\n```bash\n# Install globally first (recommended for WSL/Linux compatibility)\npnpm add -g zmcp-tools\n# If requested, approve build scripts for native dependencies\npnpm approve-builds -g\n\n# Then install MCP integration\nzmcp-tools install\n\n# Alternative: Direct installation (may have issues with Sharp in WSL)\nnpx zmcp-tools@latest install     # npm\nyarn dlx zmcp-tools@latest install  # yarn  \nbunx zmcp-tools@latest install      # bun\n```\n\n**This automatically:**\n- ✅ Installs MCP server to `~/.mcptools/server/`\n- ✅ Configures Claude Code with `claude mcp add --scope local` (current directory only)\n- ✅ Sets up project permissions and CLAUDE.md integration\n- ✅ Initializes SQLite database for agent coordination\n- ✅ Initializes LanceDB vector database for semantic search\n- ✅ Creates 61 professional MCP tools ready for use\n\n### Development Installation\n\n```bash\n# Clone and setup development environment\ngit clone https://github.com/zachhandley/ZMCPTools\ncd ZMCPTools\n\n# Quick automated setup\npnpm install \u0026\u0026 pnpm run install:global\n\n# Or manual setup\npnpm install              # Install dependencies\npnpm build               # Compile TypeScript  \npnpm link --global       # Create global symlink\nzmcp-tools install       # Configure MCP integration\n```\n\n**Development features:**\n- ✅ Global `zmcp-tools` command\n- ✅ Hot-reload development: `pnpm dev`\n- ✅ TypeScript compilation: `pnpm build`\n- ✅ Test suite: `pnpm test`\n- ✅ Full source code access and modification\n\n### MCP Server Configuration\n\nThe installer automatically configures the MCP server using `claude mcp add --scope local`. The server runs directly with Node.js:\n\n```bash\n# Automatically executed during installation\nclaude mcp add --scope local zmcp-tools node ~/.mcptools/server/index.js\n```\n\n**This provides:**\n- ✅ Core MCP server with 43 tools (including LanceDB)\n- ✅ Multi-agent orchestration capabilities\n- ✅ TypeScript type safety and performance\n- ✅ SQLite-based data persistence\n- ✅ LanceDB vector database for semantic search\n- ✅ Advanced file operations and project analysis\n- ✅ Documentation intelligence with vector embeddings\n- ✅ Foundation session caching for cost optimization\n\n## 📋 Prerequisites\n\nZMCPTools TypeScript requires the following:\n\n### Required\n- **[Node.js 18+](https://nodejs.org/)** - JavaScript runtime and LanceDB native bindings\n- **Package Manager** - npm (included), yarn, pnpm, or bun\n- **[Claude CLI](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic's Claude Code CLI\n\n### Optional\n- **TypeScript**: For development (`npm install -g typescript`)\n- **TSX**: For development hot-reload (included in devDependencies)\n\n**Note**: This TypeScript implementation includes native LanceDB vector database with no Python dependencies required.\n\n## 📝 Example Commands\n\nHere are some common workflows you can achieve with ZMCPTools:\n\n### 🎨 Brand \u0026 Style Analysis\n```\n\"Using the zmcp server, find the styles and generate me a brand guide called THEWEBSITE_BRAND.md\"\n```\n\n### 📚 Documentation Scraping\n```\n\"Scrape https://modelcontextprotocol.io/introduction -- use the selector #content-area (by ID), don't allow any subdomains, and nothing ignored (though we can ask it to ignore regex, glob, patterns to *not* get some docs), update it weekly\"\n```\n\n### 🤖 Multi-Agent Orchestration\n```\n\"Create a multi-agent orchestration to design and architect a ModelContextProtocol TypeScript server to do XYZ\"\n```\n\n### 🔍 Project Analysis\n```\n\"Analyze the project structure, and then search the .treesummary directory to see what's there\"\n```\n\n### 👥 Agent Management\n```\n\"Spawn an agent to do X, and then monitor its progress\"\n```\n\n### 🔎 Documentation Search\n```\n\"Search the documentation for X\"\n```\n\n### 🌐 Browser Automation\n```\n\"Create a browser session, navigate to https://example.com, take a screenshot, and analyze the page structure for accessibility issues\"\n```\n\n### 🧠 Knowledge Graph Operations\n```\n\"Store this implementation pattern in the knowledge graph and find related patterns we've used before\"\n```\n\n### 💾 Foundation Session Optimization\n```\n\"Create a multi-agent team with foundation session 'auth-refactor-2024' to refactor authentication across frontend and backend with 90% cost savings\"\n```\n\n### 🔄 Development Workflow\n```\n\"Start a dev server, run the test suite, and spawn an agent to fix any failing tests while monitoring progress in real-time\"\n```\n\n### 📊 Cross-Agent Learning\n```\n\"Analyze recent agent errors, identify patterns, and spawn a debugging agent that learns from previous failures\"\n```\n\n### 🎯 Streamlined Plan System\n```\n\"Create an execution plan for implementing OAuth, then execute it with coordinated agents following the plan\"\n```\n\nThe Plan system provides 4 streamlined tools for orchestration:\n- **`create_execution_plan`** - Create high-level execution plans from objectives\n- **`get_execution_plan`** - Retrieve plans with progress tracking via linked Tasks\n- **`execute_with_plan`** - Execute plans by creating coordinated Tasks for agents\n- **`list_execution_plans`** - List and monitor execution plans\n\nPlans create Tasks for implementation - Plans are high-level orchestration templates while Tasks are specific work items assigned to agents.\n\n### 📊 Data Scope\n- **Documentation \u0026 Websites**: Shared project-wide across all repositories\n- **Agents, Tasks, Memory**: Scoped per repository_path for isolation\n- **Prompts \u0026 Resources**: Available globally for all projects\n\n## 🎯 Multi-Agent Orchestration\n\n### Architect-Led Coordination\n\nZMCPTools features an AI architect that automatically analyzes objectives and spawns coordinated agent teams with proper dependencies and real-time communication.\n\n## 🎯 Usage\n\n### CLI Commands\n\n```bash\n# Show help and available commands\nzmcp-tools --help\n\n# Show system status\nzmcp-tools status\n\n# Start the MCP server\nzmcp-server\n\n# Agent management\nzmcp-tools agent list\nzmcp-tools agent spawn -t \u003ctype\u003e -r \u003crepository\u003e -d \u003cdescription\u003e\nzmcp-tools agent terminate -i \u003cagent-id\u003e\n\n# Task management\nzmcp-tools task list\nzmcp-tools task create -t \u003ctitle\u003e -d \u003cdescription\u003e\n\n# Memory operations\nzmcp-tools memory search -q \u003cquery\u003e\nzmcp-tools memory store -t \u003ctitle\u003e -c \u003ccontent\u003e\n\n# Communication rooms\nzmcp-tools room list\nzmcp-tools room join -n \u003cname\u003e\n```\n\n### 🛠️ Development Commands\n\n```bash\n# Initial setup (one time - using pnpm)\npnpm install                   # Install dependencies first\npnpm run install:global       # Build, link globally, and configure everything\n\n# Alternative package managers\nnpm install \u0026\u0026 npm run build \u0026\u0026 npm link \u0026\u0026 zmcp-tools install\nyarn install \u0026\u0026 yarn build \u0026\u0026 yarn link \u0026\u0026 zmcp-tools install\nbun install \u0026\u0026 bun run build \u0026\u0026 bun link \u0026\u0026 zmcp-tools install\n\n# Development with hot-reload\npnpm dev          # Start MCP server with tsx\npnpm dev:cli      # Start CLI with tsx\n\n# Building and testing\npnpm build        # Compile TypeScript to dist/\npnpm test         # Run Vitest tests\npnpm test:ui      # Run tests with UI\npnpm test:run     # Run tests once\n\n# Code quality\npnpm lint         # ESLint checking\npnpm typecheck    # TypeScript type checking\n\n# Production\npnpm start        # Start compiled MCP server\npnpm start:cli    # Start compiled CLI\n\n# Management\nzmcp-tools install    # Install/reinstall MCP server\nzmcp-tools uninstall  # Remove MCP server and settings\nzmcp-tools status     # Check system status\nzmcp-tools help       # Show all commands\n\n# For users who installed via npx\nnpx zmcp-tools@latest status     # Check status\nnpx zmcp-tools@latest uninstall  # Remove installation\n```\n\n**🌟 TypeScript Features:**\n\n- **🎯 Type Safety**\n  - Full TypeScript implementation with strict mode\n  - Zod schemas for runtime validation\n  - Compile-time error checking\n  - IntelliSense support in IDEs\n\n- **🚀 Performance**\n  - Better-sqlite3 for high-performance database operations\n  - ES2022 target with modern optimizations\n  - Efficient memory management\n  - Fast development with tsx hot-reload\n\n- **🧪 Testing**\n  - Vitest for modern testing experience\n  - UI mode for interactive test debugging\n  - Coverage reports with V8 provider\n  - TypeScript test support out of the box\n\n- **📦 Module System**\n  - ESNext modules for tree-shaking\n  - Clean imports and exports\n  - Library mode for programmatic use\n  - Dual CLI and server binaries\n\n### Convenient Aliases\n\nThe following aliases are available (add to `~/.zshrc`):\n\n```bash\nalias mcp-tools=\"zmcp-tools\"\nalias mcp-server=\"zmcp-server\"\nalias mcp-status=\"zmcp-tools status\"\nalias mcp-dev=\"npm run dev\"\n```\n\n## ⚙️ Configuration\n\n### TypeScript Configuration\n\n```bash\n# Build configuration in tsconfig.json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"experimentalDecorators\": true,\n    \"outDir\": \"dist\",\n    \"rootDir\": \"src\"\n  }\n}\n\n# Development scripts (works with npm/yarn/pnpm/bun)\nnpm run dev       # Hot-reload development\nnpm run build     # Production build\nnpm test          # Run test suite\n```\n\n**🎯 TypeScript Features:**\n- **Strict Type Checking**: Full type safety with strict mode enabled\n- **Modern ES Modules**: ESNext target with bundler resolution\n- **Development Tools**: tsx for hot-reload, Vitest for testing\n- **Code Quality**: ESLint with TypeScript rules\n- **Binary Generation**: Dual binaries for CLI and server\n- **Library Mode**: Exportable as TypeScript library\n\n### Manual MCP Server Configuration (if needed)\n\nThe installer automatically configures the MCP server, but if you need to manually configure it:\n\n```bash\n# For production install (via npx)\n# Server is installed at ~/.mcptools/server/index.js\n# Configuration is automatic via 'claude mcp add --scope local'\n\n# For development install\nclaude mcp add zmcp-tools $(pwd)/dist/server/index.js\n\n# Verify installation\nclaude mcp list\n\n# Test server directly\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | node ~/.mcptools/server/index.js\n```\n\n\n## 🛡️ MCP Protocol Compliance\n\n### Full MCP 1.15.0 Compatibility\n- **JSON-RPC 2.0**: Complete implementation with proper message handling\n- **Stdio Transport**: High-performance local process communication\n- **Tool Definitions**: 40 tools with comprehensive input schemas and validation\n- **Error Handling**: Standardized MCP error codes and proper error propagation\n- **Initialization Protocol**: Full handshake with capability negotiation\n\n### TypeScript MCP Implementation\nFull TypeScript implementation with MCP SDK, proper error handling, and tool management.\n\n### MCP Best Practices Implemented\n- **Input Validation**: Zod schemas for runtime type safety\n- **Proper Error Handling**: MCP-compliant error responses with detailed messages\n- **Tool Annotations**: Descriptive schemas with security hints where applicable\n- **Resource Management**: SQLite database connections with proper cleanup\n- **Transport Security**: Stdio transport for secure local communication\n\n## 🏗️ Architecture\n\n### Modern CLI with TypeScript\n- **Commander.js Framework**: Type-safe commands with automatic help generation\n- **Console Formatting**: Colored output and structured command display\n- **CLI Interface**: Comprehensive command structure for all operations\n- **Status Reporting**: Real-time feedback for operations and system health\n\n### Dual-Layer Design\n\n**Layer 1: Enhanced File Operations**\n- Hierarchical ignore pattern system (.claudeignore \u003e .gitignore \u003e defaults)\n- Fuzzy string matching with configurable similarity thresholds\n- Cross-platform screenshot capabilities with native tool integration\n\n**Layer 2: Multi-Agent Orchestration**  \n- Project analysis integration for intelligent code understanding\n- Documentation intelligence with local vector database storage\n- SQLite-based coordination with real-time communication\n- Foundation Session pattern for 85-90% token cost reduction\n\n### Enhanced Project Integration\n\n**Automatic CLAUDE.md Integration:**\n- Unique delimiters: `\u003c!-- zzZMCPToolszz START/END --\u003e`\n- Intelligent replacement of existing sections\n- Architect-led workflow guidance\n- Multi-agent examples with dependencies\n- Documentation-driven development patterns\n\n**Automatic Claude Hooks Integration:**\n- Session start context injection for instant MCP tools awareness\n- Knowledge graph and core tools reminders (analyze_project_structure(), search_knowledge_graph(), plan tools)\n- One-time per session to avoid context bloat\n- Non-destructive settings.json merging\n\n**Per-Project Setup:**\n```bash\n# Automatic integration during project setup\nzmcp-tools install --project\n\n# Creates/updates:\n# • MCP server registration via 'claude mcp add --scope local'\n# • ./.claude/commands/ (Claude commands)\n# • ./.claude/hooks/ (session start context injection)\n# • ./.claude/settings.json (hook configuration)  \n# • ./CLAUDE.md (integration guide with architect examples)\n```\n\n### Data Storage\n\n- **Installation**: Local project directory (`./dist/`)\n- **Data Directory**: `~/.mcptools/data/` (SQLite databases)\n- **Vector Storage**: `~/.mcptools/lancedb/` (LanceDB vector database)\n- **Main Database**: `~/.mcptools/data/claude_mcp_tools.db`\n- **All Data**: Agents, tasks, memory, and documentation in SQLite database\n- **Vector Data**: Embeddings and vector indices stored in LanceDB\n- **Cache**: Foundation session cache in memory/disk with vector index caching\n\n## 🛠️ Development\n\n```bash\n# Clone and setup development environment\ngit clone https://github.com/zachhandley/ZMCPTools\ncd ZMCPTools\npnpm install\n\n# Quick setup\npnpm run install:global \u0026\u0026 mcp-tools install # Build, link\n\n# Development mode\npnpm dev          # Run MCP server with hot-reload\npnpm dev:cli      # Run CLI with hot-reload\n\n# Build and test\npnpm build        # Compile TypeScript\npnpm test         # Run test suite\n\n# Test the binaries\nnode dist/index.js       # MCP server\nnode dist/cli/index.js   # CLI interface\n```\n\n## 🎨 CLI Examples\n\n### Status Display\n\n```bash\n$ zmcp-tools status\n```\n\n```\nZMCPTools Status:\n✅ TypeScript Build: dist/ directory exists\n✅ Data Directory: ~/.mcptools/data/\n✅ SQLite Database: claude_mcp_tools.db\n✅ LanceDB Vector Database: ~/.mcptools/lancedb/\n✅ MCP Server: zmcp-server binary available\n✅ Dependencies: @modelcontextprotocol/sdk, @lancedb/lancedb, better-sqlite3\n```\n\n### Development Workflow\n\n```bash\n$ npm run dev\n```\n\n```\nStarting TypeScript development server...\n✅ TypeScript compilation successful\n✅ MCP server starting on stdio\n✅ SQLite databases initialized\n✅ LanceDB vector database initialized\n✅ Agent orchestration ready\n✅ Foundation cache system active\n\nListening for MCP requests...\nPress Ctrl+C to stop\n```\n\n## 🔍 Troubleshooting\n\n### Installation Issues\n\n```bash\n# Check prerequisites\nnode --version          # Node.js 18+ required\npnpm --version          # Package manager (or npm/yarn/bun)\nclaude --version        # Claude CLI required\n\n# Clean installation\nrm -rf node_modules dist\npnpm install\npnpm build\n\n# Development installation\ngit clone https://github.com/zachhandley/ZMCPTools\ncd ZMCPTools\npnpm install \u0026\u0026 pnpm run install:global\n```\n\n### Verification\n\n```bash\n# Check build output\nls -la dist/\nnode dist/index.js --help\n\n# Check data directory\nls -la ~/.mcptools/data/\n\n# Test MCP server\nclaude mcp list\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | node dist/index.js\n```\n\n### Server Connection Issues\n\n```bash\n# Test TypeScript compilation\npnpm typecheck\npnpm lint\n\n# Test MCP server directly\nnode dist/index.js\n\n# Debug with development server\npnpm dev\n\n# Check MCP configuration\nclaude mcp list\nclaude mcp remove zmcp-tools\nclaude mcp add zmcp-tools $(pwd)/dist/index.js\n```\n\n### TypeScript Issues\n\n```bash\n# Type checking errors\npnpm typecheck                      # Check TypeScript errors\nnpx tsc --noEmit --pretty           # Detailed type errors\n\n# Runtime errors\nnode --inspect dist/index.js        # Debug with Node.js inspector\npnpm dev                            # Hot-reload development\n\n# Database issues\nrm -rf ~/.mcptools/data/*.db        # Reset databases\nnode dist/index.js                   # Reinitialize\n\n# Dependency issues\nrm -rf node_modules pnpm-lock.yaml\npnpm install                        # Clean dependency install\n```\n\n## 📈 Performance \u0026 Architecture\n\n### Production Metrics\n- **61 MCP Tools**: Complete tool suite with full type safety and MCP 1.15.0 compliance\n- **Database Performance**: SQLite with WAL mode and optimized connection pooling\n- **Vector Search**: LanceDB native TypeScript bindings for \u003c100ms semantic search\n- **Memory Efficiency**: \u003c75MB baseline with intelligent caching and cleanup\n- **Response Time**: \u003c200ms average tool execution, \u003c50ms for cached operations\n- **Cost Optimization**: 85-90% reduction through automatic foundation session management\n\n### Technical Architecture\n\n**TypeScript-First Design:**\n- Strict TypeScript with Zod schemas for runtime validation\n- Modern ES modules with tree-shaking optimization\n- Dual binary system (CLI + MCP server)\n- Hot-reload development with tsx\n\n**Database Layer:**\n- SQLite with Write-Ahead Logging for performance\n- Drizzle ORM for type-safe database operations  \n- Automatic schema migrations and connection pooling\n- LanceDB vector database for semantic search\n\n**MCP Compliance:**\n- Full MCP 1.15.0 protocol implementation\n- JSON-RPC 2.0 with proper error handling\n- Stdio and HTTP transport support\n- Resource and prompt management\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Test with Claude Code integration\n5. Submit a pull request\n\n### Development Guidelines\n- Follow TypeScript strict mode requirements\n- Add comprehensive error handling with MCP compliance\n- Include tool annotations for destructive/read-only operations\n- Test all changes with the actual MCP server integration\n\n## 📜 License\n\nMIT License - see LICENSE file for details.\n\n---\n\n**🚀 Supercharge your Claude Code workflows with ZMCPTools - TypeScript-powered multi-agent orchestration, LanceDB vector search, type-safe development, enhanced performance, and intelligent development assistance!**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzachhandley%2Fzmcptools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzachhandley%2Fzmcptools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzachhandley%2Fzmcptools/lists"}