@portkey-ai/hoot 0.2.0

package/README.md

@@ -0,0 +1,277 @@
+# 🦉 Hoot - MCP Testing Tool
+
+**Postman for MCP Servers** - A fast, lightweight tool for testing Model Context Protocol servers.
+
+## ✨ Features
+
+- 🚀 **Fast & Lightweight** - Browser-based UI with Node.js backend
+- 🔐 **Full OAuth 2.1 Support** - PKCE, automatic token refresh, secure storage
+- 🌐 **No CORS Issues** - Backend relay architecture eliminates CORS problems
+- 🎨 **Beautiful UI** - Ayu Mirage theme, smooth animations
+- 📋 **Tool Testing** - Execute tools, view results, copy responses
+- 💾 **Persistent Storage** - Servers, tools, and history cached locally
+- 🐛 **Dev Logger** - Download console logs for debugging
+- ⚡ **Real-time Feedback** - Live execution timer, toast notifications
+- 🎯 **Smart UX** - Empty states, error boundaries, loading skeletons
+
+## 🚀 Quick Start
+
+### Run with npx (Recommended)
+```bash
+npx -y @portkey-ai/hoot
+```
+
+That's it! This command will:
+- ✅ Install Hoot if not already installed
+- ✅ Start the backend server on `http://localhost:3002`
+- ✅ Start the frontend UI on `http://localhost:5173`
+- ✅ Open your browser automatically
+
+Press `Ctrl+C` to stop both servers.
+
+### Install Globally (Alternative)
+```bash
+npm install -g @portkey-ai/hoot
+hoot
+```
+
+### Development Setup
+If you want to contribute or develop locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/hoot.git
+cd hoot
+
+# Install dependencies
+npm install
+
+# Start both backend and frontend
+npm run dev:full
+
+# Or start them separately
+npm run backend  # Terminal 1
+npm run dev      # Terminal 2
+```
+
+This starts:
+- **Backend MCP Server** on `http://localhost:3002` (handles MCP connections)
+- **Hoot UI** on `http://localhost:5173` (Vite dev server)
+
+## 📖 Usage
+
+1. **Start Hoot** - Run `npx -y @portkey-ai/hoot`
+2. **Add Server** - Click "+ Add Server"
+3. **Configure**:
+   - Name: "My MCP Server"
+   - Transport: HTTP or SSE
+   - URL: https://your-mcp-server.com
+   - Auth: None / Headers / OAuth
+4. **Connect** - Server appears in sidebar with tool count
+5. **Select Tool** - Click any tool to test it
+6. **Execute** - Fill params, click "EXECUTE TOOL"
+7. **View Results** - Response, Raw JSON, or Request tabs
+
+## 🏗️ Architecture
+
+Hoot uses a **backend relay architecture** to eliminate CORS issues:
+
+```
+Browser App (React) → Backend Server (Node.js) → MCP Servers
+     (UI)                  (MCP Client)           (External)
+```
+
+- **Frontend**: React UI running in browser
+- **Backend**: Node.js server with MCP SDK (handles actual connections)
+- **Communication**: REST API over localhost (no CORS issues)
+
+See [docs/BACKEND_ARCHITECTURE.md](./docs/BACKEND_ARCHITECTURE.md) for detailed architecture documentation.
+
+## 🌐 No More CORS Issues!
+
+The backend relay architecture completely eliminates CORS issues. The Node.js backend acts as the MCP client and communicates server-to-server with MCP servers, while the browser UI simply relays requests through the local backend.
+
+**Benefits**:
+- ✅ Works with any MCP server (no CORS configuration needed)
+- ✅ More secure (credentials stay on backend)
+- ✅ Better performance (persistent connections)
+- ✅ Full OAuth 2.1 support maintained
+
+**Old CORS Proxy (deprecated)**: The old proxy method is still available via `npm run dev:with-proxy`, but the backend relay is now the recommended approach.
+
+**See [docs/BACKEND_ARCHITECTURE.md](./docs/BACKEND_ARCHITECTURE.md) for detailed architecture documentation.**
+
+## 🔐 OAuth 2.1 Support
+
+Hoot supports full OAuth 2.1 authorization flow:
+
+- ✅ Authorization redirect with PKCE
+- ✅ Automatic token exchange  
+- ✅ Token refresh
+- ✅ Secure storage (SQLite database)
+- ✅ Multiple servers with different auth
+
+**See [docs/AUTHENTICATION.md](./docs/AUTHENTICATION.md) for details.**
+
+## 🎨 UI Features
+
+### Toasts
+- Connection errors
+- Execution errors  
+- Proxy status changes
+- Copy failures
+
+### Empty States
+- No servers: "Add your first server"
+- No tools: "Server doesn't expose tools"
+- No tool selected: "Select a tool to test"
+
+### Live Feedback
+- **Execute button timer**: Shows elapsed time during execution
+- **Spinning icons**: Refresh actions
+- **Copy buttons**: One-click copy with checkmark feedback
+- **Status dots**: Green (connected) / Gray (disconnected)
+
+### Dev Logger
+```javascript
+// In browser console:
+hootLogger.download()  // Download logs to file
+hootLogger.get()       // View in console
+hootLogger.clear()     // Clear logs
+hootLogger.count()     // Get log count
+```
+
+## 📂 Project Structure
+
+```
+hoot/
+├── bin/
+│   └── hoot.js          # CLI entry point
+├── src/
+│   ├── components/      # React components
+│   │   ├── ServerSidebar.tsx
+│   │   ├── ToolsSidebar.tsx
+│   │   ├── MainArea.tsx
+│   │   └── ...
+│   ├── stores/          # Zustand state management
+│   │   ├── appStore.ts
+│   │   └── toastStore.ts
+│   ├── hooks/           # Custom React hooks
+│   │   ├── useMCP.ts
+│   │   └── useAutoReconnect.ts
+│   ├── lib/             # Core libraries
+│   │   ├── mcpClient.ts      # MCP SDK wrapper
+│   │   ├── backendClient.ts  # Backend API client
+│   │   ├── oauthProvider.ts  # OAuth implementation
+│   │   └── logger.ts         # Dev logger
+│   └── types/           # TypeScript types
+├── docs/                # Documentation
+│   ├── ARCHITECTURE.md
+│   ├── AUTHENTICATION.md
+│   ├── BACKEND_ARCHITECTURE.md
+│   └── ...
+├── mcp-backend-server.js  # Backend MCP relay server
+└── package.json
+```
+
+## 📚 Documentation
+
+- [Architecture Overview](./docs/ARCHITECTURE.md)
+- [Backend Architecture](./docs/BACKEND_ARCHITECTURE.md)
+- [Authentication & OAuth](./docs/AUTHENTICATION.md)
+- [Design System](./docs/DESIGN_HOOT.md)
+- [Quick Start Guide](./docs/QUICKSTART.md)
+- [Troubleshooting](./docs/TROUBLESHOOTING.md)
+- [Full Documentation Index](./docs/README.md)
+
+## 🛠️ npm Scripts
+
+```bash
+npx -y @portkey-ai/hoot  # Run Hoot (recommended)
+npm start                # Start both backend + frontend
+npm run dev              # Start Hoot UI only
+npm run backend          # Start backend server only
+npm run dev:full         # Start both (concurrently)
+npm run build            # Build for production
+npm run preview          # Preview production build
+```
+
+## 🔧 Tech Stack
+
+- **React 19** - UI framework
+- **TypeScript** - Type safety
+- **Vite** - Build tool
+- **Zustand** - State management
+- **MCP SDK** - Model Context Protocol
+- **Express** - Proxy server
+- **Lucide React** - Icons
+
+## 📊 Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+
+## 🐛 Debugging
+
+### Enable Dev Logger
+Automatically enabled in development. Access via browser console:
+```javascript
+hootLogger.download()
+```
+
+### Check Proxy Status
+```bash
+curl http://localhost:3001/health
+```
+
+### View Console Logs
+All MCP operations are logged with emojis:
+- 🦉 Proxy server
+- 🔧 Transport creation
+- 🔌 Connections
+- 🔐 OAuth flows
+- ✓ Success
+- ❌ Errors
+
+## 📝 Roadmap
+
+### v0.2 (Current)
+- [x] Full OAuth 2.1 support
+- [x] CORS proxy
+- [x] UI polish (toasts, empty states, copy buttons)
+- [x] Live execution timer
+- [x] Dev logger
+
+### v0.3 (Planned)
+- [ ] Resource testing UI
+- [ ] Prompt testing UI  
+- [ ] Keyboard shortcuts (Cmd+K, Cmd+E)
+- [ ] Browser extension (CORS bypass)
+
+### v1.0 (Future)
+- [ ] Electron app (stdio transport support)
+- [ ] Encrypted credential storage
+- [ ] Advanced testing features
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
+1. Fork the repo
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## 📄 License
+
+MIT
+
+## 🙏 Acknowledgments
+
+- **MCP SDK** - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
+- **Ayu Theme** - Color palette inspiration
+- **Lucide** - Beautiful icons
+
+---
+
+Made with 🦉 by developers, for developers.

package/RELEASE_READY.md

@@ -0,0 +1,210 @@
+# 🎉 Hoot - Ready for Open Source Release!
+
+## Summary
+
+Your project is now fully prepared for open-source release with `npx -y hoot` support!
+
+## ✅ What Was Done
+
+### 1. **Project Reorganization**
+- Created `docs/` directory and moved 24+ documentation files
+- Created `tests/` directory and moved test files
+- Created `examples/` directory for example files  
+- Created `bin/` directory for CLI entry point
+- **Removed 15+ redundant/obsolete documentation files**
+- Root folder is now clean and professional
+
+### 2. **Removed Redundant Documentation**
+The following duplicate and obsolete files were deleted:
+- `HOOT_README.md` - Duplicate README
+- `SCREECH_README.md` - Old project name
+- `CORS.md`, `CORS_PROXY.md` - Redundant CORS docs
+- `DESIGN.md` - Old design doc (kept DESIGN_HOOT.md)
+- `STATUS.md`, `WORKING.md`, `SUCCESS.md` - Dev status files
+- `CORS_PROXY_IMPLEMENTATION.md` - Implementation detail
+- `BACKEND_RELAY_COMPLETE.md` - Implementation detail
+- `OAUTH_PROXY_FIX.md` - Old fix documentation
+- `OAUTH_V02_IMPLEMENTATION.md` - Implementation detail
+- `UI_POLISH_COMPLETE.md` - Implementation detail
+- `UI_POLISH_SUMMARY.md` - Implementation detail
+- `V0.1_COMPLETE.md` - Old release notes
+
+### 3. **NPX Support (Main Feature!)**
+Created `bin/hoot.js` - A CLI entry point that:
+- Auto-starts the backend server (port 3002)
+- Auto-starts the frontend dev server (port 5173)
+- Opens the browser automatically
+- Handles graceful shutdown with Ctrl+C
+
+Users can now simply run:
+```bash
+npx -y hoot
+```
+
+### 4. **Package Configuration**
+Updated `package.json` with:
+- ✅ `bin` field pointing to `./bin/hoot.js`
+- ✅ `start` script for easy launching
+- ✅ `prepublishOnly` script (auto-builds before publishing)
+- ✅ Repository URLs (already set to `portkey-ai/hoot`)
+- ✅ Proper keywords for npm discovery
+- ✅ Node.js version requirement (>=18.0.0)
+
+### 5. **Publishing Preparation**
+Created essential files:
+- `.npmignore` - Excludes dev files from npm package
+- `CONTRIBUTING.md` - Contribution guidelines
+- `LICENSE` - MIT license
+- `PUBLISHING.md` - Detailed npm publishing guide
+- `PRE_PUBLISH_CHECKLIST.md` - Steps before publishing
+- `TEST_LOCALLY.md` - Local testing instructions
+
+### 6. **Documentation Cleanup**
+Remaining clean documentation structure:
+
+**Root Level (6 files):**
+- `README.md` - Main documentation
+- `CONTRIBUTING.md` - How to contribute
+- `LICENSE` - MIT license
+- `PUBLISHING.md` - Publishing guide
+- `PRE_PUBLISH_CHECKLIST.md` - Pre-publish steps
+- `TEST_LOCALLY.md` - Testing guide
+
+**docs/ Directory (13 files):**
+- `README.md` - Documentation index
+- `ARCHITECTURE.md` - System architecture
+- `AUTHENTICATION.md` - OAuth 2.1 guide
+- `BACKEND_ARCHITECTURE.md` - Backend details
+- `CHANGELOG.md` - Version history
+- `DESIGN_HOOT.md` - Design system
+- `EXAMPLES.md` - Usage examples
+- `MIGRATION_GUIDE.md` - Migration guide
+- `QUICKSTART.md` - Quick start
+- `STORAGE.md` - Storage system
+- `TRANSPORTS.md` - MCP transports
+- `TROUBLESHOOTING.md` - Common issues
+- `V0.2_ROADMAP.md` - Future plans
+
+## 📊 Package Statistics
+
+- **Root markdown files:** 6 (down from 25+)
+- **Documentation files:** 13 (well-organized)
+- **Test files:** 4
+- **Example files:** 1
+- **README.md:** 277 lines
+- **CLI entry point:** 122 lines
+
+## 🚀 How It Works
+
+When users run `npx -y hoot`:
+
+1. npm downloads and caches Hoot (if not already installed)
+2. Runs `bin/hoot.js`
+3. Script starts backend server on port 3002
+4. Script starts frontend on port 5173 with `--open` flag
+5. Browser opens automatically to http://localhost:5173
+6. User can immediately start testing MCP servers!
+7. Ctrl+C gracefully shuts down both servers
+
+## 📦 What's Included in npm Package
+
+Files included (see `.npmignore`):
+- ✅ `bin/` - CLI scripts
+- ✅ `dist/` - Built frontend assets
+- ✅ `mcp-backend-server.js` - Backend server
+- ✅ `proxy-server.js` - Optional proxy
+- ✅ `package.json` - Package metadata
+- ✅ `README.md` - Documentation
+- ✅ `LICENSE` - License file
+
+Files excluded:
+- ❌ `src/` - Source TypeScript files (use dist/)
+- ❌ `docs/` - Documentation files
+- ❌ `tests/` - Test files
+- ❌ `examples/` - Example files
+- ❌ `node_modules/` - Dependencies
+- ❌ Development config files
+
+## 🎯 Next Steps
+
+### Before Publishing:
+
+1. **Test locally:**
+   ```bash
+   npm start
+   ```
+   Should start both servers and open browser.
+
+2. **Build for production:**
+   ```bash
+   npm run build
+   ```
+
+3. **Test the package:**
+   ```bash
+   npm pack
+   npm install -g ./hoot-0.2.0.tgz
+   hoot
+   npm uninstall -g hoot
+   rm hoot-0.2.0.tgz
+   ```
+
+4. **Publish to npm:**
+   ```bash
+   npm login
+   npm publish
+   ```
+
+5. **Verify it works:**
+   ```bash
+   npx -y hoot
+   ```
+
+### After Publishing:
+
+1. Create a GitHub release with v0.2.0 tag
+2. Share on social media
+3. Update any related documentation
+
+## 📖 Important Files to Review
+
+Before publishing, review these files:
+
+1. **PRE_PUBLISH_CHECKLIST.md** - Complete checklist
+2. **PUBLISHING.md** - Detailed publishing guide
+3. **TEST_LOCALLY.md** - Testing instructions
+4. **README.md** - User-facing documentation
+5. **package.json** - Already has correct repository URLs
+
+## 🎉 Success Criteria
+
+- ✅ Root folder is clean (only 6 markdown files)
+- ✅ Documentation is well-organized in `docs/`
+- ✅ Redundant files removed (15+ files deleted)
+- ✅ NPX support configured
+- ✅ Package.json properly configured
+- ✅ .npmignore excludes dev files
+- ✅ Contributing guidelines in place
+- ✅ MIT license included
+- ✅ Repository URLs set to portkey-ai/hoot
+
+## 🚀 Ready to Ship!
+
+Your project is production-ready! Users will be able to:
+
+```bash
+npx -y hoot
+```
+
+And start testing MCP servers immediately with zero configuration!
+
+---
+
+**Questions?** Check the detailed guides:
+- `PRE_PUBLISH_CHECKLIST.md` - What to do before publishing
+- `PUBLISHING.md` - How to publish to npm
+- `TEST_LOCALLY.md` - How to test locally
+- `CONTRIBUTING.md` - Development workflow
+
+**Happy shipping! 🦉**
+

package/TEST_LOCALLY.md

@@ -0,0 +1,98 @@
+# Quick Start - Testing the Package Before Publishing
+
+## Test the CLI Locally
+
+Before publishing to npm, test that everything works:
+
+### 1. Test the start script
+```bash
+npm start
+```
+
+This should:
+- Start the backend server on port 3002
+- Start the frontend on port 5173
+- Open your browser automatically
+
+Press `Ctrl+C` to stop.
+
+### 2. Test the CLI directly
+```bash
+node bin/hoot.js
+```
+
+Should behave the same as `npm start`.
+
+### 3. Test as a local package
+```bash
+# Create a test tarball
+npm pack
+
+# Install it globally from the tarball
+npm install -g ./hoot-0.2.0.tgz
+
+# Run it
+hoot
+
+# Clean up
+npm uninstall -g hoot
+rm hoot-0.2.0.tgz
+```
+
+### 4. Test in a different directory
+```bash
+# Go to a different directory
+cd /tmp
+
+# Run the global command (if still installed)
+hoot
+
+# Or test with the tarball
+npm install -g /path/to/hoot-0.2.0.tgz
+hoot
+```
+
+## What to Check
+
+- ✅ Backend starts without errors
+- ✅ Frontend starts without errors
+- ✅ Browser opens automatically
+- ✅ Can add a server in the UI
+- ✅ Can connect to an MCP server
+- ✅ Can execute tools
+- ✅ OAuth flow works (if testing with OAuth server)
+- ✅ Ctrl+C cleanly shuts down both servers
+
+## Common Issues
+
+### Port already in use
+If port 3002 or 5173 is already in use:
+```bash
+# Find and kill the process
+lsof -ti:3002 | xargs kill -9
+lsof -ti:5173 | xargs kill -9
+```
+
+### Permission denied
+Make sure the CLI script is executable:
+```bash
+chmod +x bin/hoot.js
+```
+
+### Module not found
+Make sure dependencies are installed:
+```bash
+npm install
+```
+
+## Ready to Publish?
+
+Once everything tests successfully:
+
+1. Update version if needed: `npm version patch`
+2. Build: `npm run build`
+3. Publish: `npm publish`
+4. Test from npm: `npx -y hoot`
+
+See `PUBLISHING.md` for detailed publishing instructions.
+