@portkey-ai/hoot 0.13.0 → 0.15.0

package/README.md

@@ -1,106 +1,216 @@
-# 🦉 hoot
-> **⚠️ early beta** - things might break. if they do, [open an issue](https://github.com/Portkey-AI/hoot/issues).
-> 
-> **🤝 contributions welcome** - see something that could be better? PRs are appreciated!
+# 🦉 Hoot
 
-testing tool for MCP servers. like postman but for MCP.
+[![npm version](https://img.shields.io/npm/v/@portkey-ai/hoot?color=5ccfe6&label=version)](https://www.npmjs.com/package/@portkey-ai/hoot)
+[![npm downloads](https://img.shields.io/npm/dm/@portkey-ai/hoot?color=5ccfe6)](https://www.npmjs.com/package/@portkey-ai/hoot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-5ccfe6.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@portkey-ai/hoot?color=5ccfe6)](https://nodejs.org)
 
+**MCP Testing Tool** — Like Postman, but for the Model Context Protocol.
+
+Test, debug, and explore MCP servers with a beautiful interface. No AI chat needed.
 
 https://github.com/user-attachments/assets/e3add38e-9636-4f40-99d8-f4a2b8f0f056
 
+> **⚠️ Beta Software** — Hoot is in active development. Found a bug? [Open an issue](https://github.com/Portkey-AI/hoot/issues). Want to contribute? [PRs welcome](./CONTRIBUTING.md)!
+
+## Quick Start
 
-## why
+**🌐 Try instantly (no install):**
 
-needed a quick way to test MCP servers without spinning up a whole AI chat interface.
+👉 **[hoot.run](https://hoot.run)** — Opens in your browser, ready to test.
 
-## install
+**Or run locally:**
 
 ```bash
 npx -y @portkey-ai/hoot
 ```
 
-that's it. opens on localhost:8009
-
-or install globally if you want:
-```bash
-npm install -g @portkey-ai/hoot
-hoot
-```
+Opens on `localhost:8009`. One command, zero config.
 
 ![npx-hoot](https://github.com/user-attachments/assets/3c8c80e2-6ad3-439e-80eb-e2f6c4d22d8e)
 
 
-## what works
+## Features
 
-- connect to MCP servers (http/sse)
-- **auto-detection** - just paste a URL, we figure out the rest
-- see what tools they have
-- execute tools with params
-- view responses
-- oauth 2.1 if your server needs it
-- copy stuff to clipboard
-- **🦉 "try in hoot" links** - share servers with just a URL ([docs](./docs/TRY_IN_HOOT.md))
-- **8 beautiful themes** - light & dark modes ([docs](./docs/THEMES.md))
+### Core Testing
+- **Connect to any MCP server** — HTTP and SSE transport support
+- **Auto-detection** — Just paste a URL, Hoot figures out the rest
+- **Execute tools** — Test tools with parameters and view responses
+- **Copy-paste friendly** — Everything is clipboard-ready
 
-## how it works
+### Authentication & Security
+- **OAuth 2.1** with automatic discovery and compliance testing ([docs](./docs/OAUTH-COMPLIANCE-COMPLETE.md))
+- **JWT-based sessions** — Secure local authentication
+- **Rate limiting & audit logs** — Built-in security features
+- **Localhost-only by default** — Safe for local development
 
-runs a node.js backend that connects to MCP servers (because CORS is annoying). react frontend talks to the backend over localhost.
+### Smart Features
+- **Intelligent tool filtering** — Context-aware tool selection powered by AI
+- **Chat interface** — Test tools conversationally with LLM assistance
+- **Keyboard shortcuts** — Lightning-fast navigation ([docs](./docs/KEYBOARD_SHORTCUTS.md))
+- **8 beautiful themes** — Light & dark modes for every preference ([docs](./docs/THEMES.md))
+
+### Sharing & Collaboration
+- **🦉 "Try in Hoot" links** — Share servers with a single URL ([docs](./docs/TRY_IN_HOOT.md))
+- **Persistent state** — Your servers and tools stay configured between sessions
+
+## How It Works
+
+Hoot runs a Node.js backend that acts as the MCP client, eliminating CORS issues when connecting to MCP servers from your browser.
 
 ```
-browser → backend → mcp servers
+Browser (React) → Backend (Node.js/Express) → MCP Servers
 ```
 
-no cors issues. backend handles oauth tokens in sqlite.
+**Architecture highlights:**
+- **No CORS headaches** — Backend handles all MCP connections
+- **Persistent OAuth tokens** — Stored securely in SQLite (`~/.hoot/hoot-mcp.db`)
+- **Session-based auth** — JWT tokens for secure frontend-backend communication
+- **Edge-ready** — Deploy to Cloudflare Workers for global hosting ([guide](./docs/CLOUDFLARE_DEPLOYMENT.md))
+
+### Data Persistence
 
-### persistence
+**On hoot.run:**
+- **Server configs & tools** — Saved in browser localStorage
+- **OAuth tokens** — Managed by the hosted backend
+- **Chat history** — Preserved in localStorage
 
-- **server configs & tools**: saved in browser localStorage (survives page refreshes)
-- **oauth tokens**: stored in `~/.hoot/hoot-mcp.db` (persists across npx runs)
+**On local (npx/npm):**
+- **Server configs & tools** — Saved in browser localStorage
+- **OAuth tokens** — Stored in `~/.hoot/hoot-mcp.db` (persists across npx runs)
+- **Chat history** — Preserved in localStorage
 
-your servers stay configured between sessions, even when running with `npx`!
+Your servers stay configured between sessions!
 
-## running from source
+## Development
+
+**Run from source:**
 
 ```bash
-git clone <repo>
+git clone https://github.com/Portkey-AI/hoot
+cd hoot
 npm install
 npm run dev:full
 ```
 
-backend runs on 8008, frontend on 8009.
+- Backend runs on `localhost:8008`
+- Frontend runs on `localhost:8009`
+
+**Available scripts:**
+- `npm run dev:full` — Run both frontend and backend
+- `npm run backend` — Backend only
+- `npm run dev` — Frontend only
+- `npm run build` — Build for npm distribution
+- `npm run build:cloudflare` — Build for Cloudflare Workers
 
-## debugging
+### Debugging
 
-there's a logger in the console:
+Hoot includes a client-side logger accessible from the browser console:
 
 ```javascript
-hootLogger.download()  // get logs
+hootLogger.download()  // Download logs as JSON
+hootLogger.clear()     // Clear logs
 ```
 
-## 🔒 security
+Backend logs are written to `backend.log`. See [logging docs](./docs/LOGGING.md) for details.
+
+## Documentation
+
+- **[Quick Start Guide](./docs/QUICKSTART.md)** — Get up and running in 5 minutes
+- **[Try in Hoot](./docs/TRY_IN_HOOT.md)** — Share servers with one-click links
+- **[Authentication](./docs/AUTHENTICATION.md)** — OAuth 2.1 and API key setup
+- **[Themes](./docs/THEMES.md)** — Customize your interface
+- **[Keyboard Shortcuts](./docs/KEYBOARD_SHORTCUTS.md)** — Work faster
+- **[Architecture](./docs/ARCHITECTURE.md)** — How Hoot is built
+- **[Security](./docs/SECURITY.md)** — Security features and best practices
+- **[Cloudflare Deployment](./docs/CLOUDFLARE_DEPLOYMENT.md)** — Deploy to the edge
+
+[📚 Full Documentation](./docs/)
+
+## Why Hoot?
+
+| Feature | Hoot | Manual curl/testing |
+|---------|------|---------------------|
+| **OAuth 2.1 support** | ✅ Automatic discovery & flow | ❌ Manual token management |
+| **Transport auto-detection** | ✅ HTTP/SSE auto-detected | ❌ Manual configuration |
+| **Visual interface** | ✅ Beautiful UI | ❌ Terminal only |
+| **Tool filtering** | ✅ AI-powered context-aware | ❌ None |
+| **Session persistence** | ✅ Configs & tokens saved | ❌ Reauth every time |
+| **Share configurations** | ✅ One-click "Try in Hoot" links | ❌ Copy-paste configs |
+
+## FAQ
 
-hoot includes built-in security features for safe local development:
-- ✅ session-based authentication
-- ✅ rate limiting
-- ✅ audit logging
-- ✅ localhost-only access
+<details>
+<summary><strong>Does Hoot work with all MCP servers?</strong></summary>
 
-runs securely on your local machine. [read more](./docs/SECURITY.md)
+Yes! Hoot supports both HTTP and SSE transports, OAuth 2.1, and API key authentication. We auto-detect server configurations to make connection as seamless as possible.
+</details>
 
-## what's missing
+<details>
+<summary><strong>Is my data secure?</strong></summary>
 
-- resources (coming)
-- prompts (coming)
-- more tests (working on it)
+Yes. Hoot runs entirely on your local machine. OAuth tokens are stored in a local SQLite database (`~/.hoot/hoot-mcp.db`), and all communication happens over localhost. No data is sent to external servers.
+</details>
 
-## tech
+<details>
+<summary><strong>Can I use Hoot in production?</strong></summary>
 
-react 19, typescript, vite, zustand, express, MCP SDK
+Hoot is designed for development and testing. For production deployments, you can deploy Hoot to Cloudflare Workers for your team. See our [deployment guide](./docs/CLOUDFLARE_DEPLOYMENT.md).
+</details>
 
-## license
+<details>
+<summary><strong>How do I test servers that require OAuth?</strong></summary>
 
-MIT
+Just add the server URL. Hoot automatically detects OAuth requirements and guides you through the authorization flow. Tokens are stored securely and refreshed automatically.
+</details>
+
+<details>
+<summary><strong>Can I test multiple servers at once?</strong></summary>
+
+Absolutely! Connect to as many servers as you need. Hoot manages all connections simultaneously and lets you switch between them instantly.
+</details>
+
+<details>
+<summary><strong>Does Hoot support resources and prompts?</strong></summary>
+
+Not yet, but they're coming soon! Currently, Hoot focuses on tool testing. Resources and prompts are on our roadmap.
+</details>
+
+## Roadmap
+
+We're working towards full MCP specification support. Coming soon:
+
+- **Resources** — MCP resource listing and reading
+- **Prompts** — MCP prompt testing and execution
+- **Electron desktop app** — Native app with stdio transport support
+- **Collaborative workspaces** — Share server configs with teams
+
+Want to contribute? Check out [CONTRIBUTING.md](./CONTRIBUTING.md) or [open an issue](https://github.com/Portkey-AI/hoot/issues) with feature requests!
+
+## Technology Stack
+
+- **Frontend** — React 19, TypeScript, Vite, Zustand
+- **Backend** — Node.js, Express, MCP SDK
+- **Database** — SQLite (better-sqlite3)
+- **Deployment** — npm, Cloudflare Workers + Durable Objects
+- **AI** — Workers AI for semantic tool filtering
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+**Ways to contribute:**
+- 🐛 Report bugs and issues
+- 💡 Suggest new features
+- 📝 Improve documentation
+- 🔧 Submit pull requests
+
+## License
+
+MIT License — see [LICENSE](./LICENSE) for details.
 
 ---
 
-made this because i was tired of curl-ing MCP servers. hope it helps.
+**Built by [Portkey](https://portkey.ai)** — Making AI development easier, one tool at a time.
+
+Made this because we were tired of curl-ing MCP servers. Hope it helps! 🦉

package/TEST_INFRASTRUCTURE.md

@@ -0,0 +1,107 @@
+# Hoot Test Infrastructure
+
+Production-ready test MCP server with OAuth 2.1 for comprehensive Hoot testing.
+
+## Quick Start
+
+```bash
+# Interactive demo
+npm run test:quick-start
+
+# Start test server manually
+npm run test:server
+
+# Run tests
+npm test
+```
+
+## Test Server Endpoints
+
+| Endpoint | URL |
+|----------|-----|
+| MCP | `http://localhost:9000/mcp` |
+| Health | `http://localhost:9000/health` |
+| OAuth Discovery | `http://localhost:9001/.well-known/oauth-authorization-server` |
+| OAuth Authorize | `http://localhost:9001/oauth/authorize` |
+| OAuth Token | `http://localhost:9001/oauth/token` |
+
+## Test Credentials
+
+| Type | Client ID | Secret | API Key |
+|------|-----------|--------|---------|
+| OAuth Public | `test-client-public` | - | - |
+| OAuth Confidential | `test-client-confidential` | `test-secret-123` | - |
+| API Key | - | - | `test-api-key-valid` |
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `echo` | Echo back input |
+| `add` | Add two numbers |
+| `get_weather` | Mock weather data |
+| `complex_tool` | Nested parameters |
+| `long_running_task` | Simulated delay |
+| `error_generator` | Generate errors |
+
+## Usage in Tests
+
+```javascript
+import { TestServerManager } from './helpers/server-manager.js';
+import { validServerConfigs, toolTestCases } from './helpers/test-data.js';
+
+describe('My Tests', () => {
+  let server;
+  
+  beforeAll(async () => {
+    server = new TestServerManager();
+    await server.start();
+  });
+  
+  afterAll(async () => {
+    await server.stop();
+  });
+  
+  it('should work', async () => {
+    // server.mcpUrl, server.oauthUrl, server.getTestCredentials()
+  });
+});
+```
+
+## Manual Testing with Hoot
+
+```bash
+# Terminal 1: Test server
+npm run test:server
+
+# Terminal 2: Hoot backend  
+npm run server
+
+# Terminal 3: Hoot frontend
+npm run dev
+```
+
+Connect Hoot to `http://localhost:9000/mcp` with OAuth using custom endpoints.
+
+## Architecture
+
+```
+tests/
+├── mock-servers/
+│   └── test-mcp-server.js    # MCP + OAuth server (~900 lines)
+├── helpers/
+│   ├── server-manager.js     # Server lifecycle
+│   └── test-data.js          # Test fixtures
+├── example-mcp-lifecycle.test.js
+├── global-setup.js
+└── quick-start.js
+```
+
+## Features
+
+- ✅ Full MCP protocol (2025-11-25 spec)
+- ✅ OAuth 2.1 with PKCE (required)
+- ✅ Custom OAuth endpoints
+- ✅ API key authentication
+- ✅ Rate limiting, logging, health checks
+- ✅ Comprehensive test fixtures