{"id":33265920,"url":"https://github.com/portel-dev/ncp","last_synced_at":"2026-04-10T10:03:17.619Z","repository":{"id":315207500,"uuid":"1057060209","full_name":"portel-dev/ncp","owner":"portel-dev","description":"Natural Context Provider (NCP). Your MCPs, supercharged. Find any tool instantly, load on demand, run on schedule, ready for any   client. Smart loading saves tokens and energy.","archived":false,"fork":false,"pushed_at":"2026-03-07T02:32:10.000Z","size":34960,"stargazers_count":77,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-07T06:28:07.186Z","etag":null,"topics":["ai-agents","claude","claude-desktop","gemini","mcp","mcp-client","mcp-server","openai","orchestrator","vector-search"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/portel-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T08:16:40.000Z","updated_at":"2026-03-07T03:47:12.000Z","dependencies_parsed_at":"2025-12-13T04:08:26.882Z","dependency_job_id":null,"html_url":"https://github.com/portel-dev/ncp","commit_stats":null,"previous_names":["portel-dev/ncp"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/portel-dev/ncp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fncp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fncp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fncp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fncp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/portel-dev","download_url":"https://codeload.github.com/portel-dev/ncp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fncp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31637748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agents","claude","claude-desktop","gemini","mcp","mcp-client","mcp-server","openai","orchestrator","vector-search"],"created_at":"2025-11-17T07:00:34.357Z","updated_at":"2026-04-10T10:03:17.613Z","avatar_url":"https://github.com/portel-dev.png","language":"JavaScript","funding_links":[],"categories":["Aggregators \u0026 Gateways","Language-Specific SDKs","📦 Other","📚 Projects (2474 total)","MCP Servers Directory","📂 카테고리"],"sub_categories":["Aggregators","Utilities","MCP Servers","Quick Submission","🔗 Aggregators"],"readme":"[![npm version](https://img.shields.io/npm/v/%40portel%2Fncp.svg)](https://www.npmjs.com/package/@portel/ncp)\n[![npm downloads](https://img.shields.io/npm/dt/@portel/ncp?label=downloads)](https://www.npmjs.com/package/@portel/ncp)\n[![GitHub release downloads](https://img.shields.io/github/downloads/portel-dev/ncp/total?label=.dxt%20downloads)](https://github.com/portel-dev/ncp/releases)\n[![Latest release](https://img.shields.io/github/downloads/portel-dev/ncp/latest/total?label=latest%20.dxt)](https://github.com/portel-dev/ncp/releases/latest)\n[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic--2.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)\n\n\u003c!-- mcp-name: io.github.portel-dev/ncp --\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/ncp.svg\" alt=\"NCP Logo\" width=\"200\" height=\"200\"\u003e\n\n# NCP - Natural Context Provider\n\n\u003e **1 MCP to rule them all**\n\n\u003c/div\u003e\n\nYour MCPs, [supercharged](#-supercharged-features). Find any tool instantly, execute with code mode, run on schedule, discover skills, load Photons, ready for any client. Smart loading saves tokens and energy.\n\n## 💍 **What is NCP?**\n\nInstead of your AI juggling 50+ tools scattered across different MCPs, NCP gives it a single, unified interface with **code mode execution, scheduling, skills discovery, and custom Photons**.\n\nYour AI sees just **2-3 simple tools:**\n- **`find`** - Search for any tool, skill, or Photon: \"I need to read a file\" → finds the right tool automatically\n- **`code`** - Execute TypeScript directly: `await github.create_issue({...})` (code mode, enabled by default)\n- **`run`** - Execute tools individually (when code mode is disabled)\n\nBehind the scenes, NCP manages all 50+ tools + skills + Photons: routing requests, discovering the right capability, executing code, scheduling tasks, managing health, and caching responses.\n\n![NCP Transformation Flow](docs/images/ncp-transformation-flow.png)\n\n**Why this matters:**\n- Your AI stops analyzing \"which tool do I use?\" and starts doing actual work\n- **Code mode** lets AI write multi-step TypeScript workflows combining tools, skills, and scheduling\n- **Skills** provide domain expertise: canvas design, PDF manipulation, document generation, more\n- **Photons** enable custom TypeScript MCPs without npm publishing\n- **97% fewer tokens burned** on tool confusion (2,500 vs 103,000 for 80 tools)\n- **5x faster responses** (sub-second tool selection vs 5-8 seconds)\n- **Your AI becomes focused.** Not desperate.\n\n🚀 **NEW:** Project-level configuration - each project can define its own MCPs automatically\n\n\u003e **What's MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic lets AI assistants connect to external tools and data sources. Think of MCPs as \"plugins\" that give your AI superpowers like file access, web search, databases, and more.\n\n---\n\n## 📑 **Quick Navigation**\n\n- [The Problem](#-the-mcp-paradox-from-assistant-to-desperate) - Why too many tools break your AI\n- [The Solution](#-the-before--after-reality) - How NCP transforms your experience\n- [Getting Started](#-prerequisites) - Installation \u0026 quick start\n- [Try It Out](#-test-drive-see-the-difference-yourself) - See the CLI in action\n- [Supercharged Features](#-supercharged-features) - How NCP empowers your MCPs\n- [Setup by Client](#️-configuration-for-different-ai-clients) - Claude Desktop, Cursor, VS Code, etc.\n- [Popular MCPs](#-popular-mcps-that-work-great-with-ncp) - Community favorites to add\n- [Advanced Features](#-advanced-features) - Project config, scheduling, remote MCPs\n- [Troubleshooting](#-troubleshooting) - Common issues \u0026 solutions\n- [How It Works](#-deep-dive-how-it-works) - Technical deep dive\n- [Contributing](#-contributing) - Help us improve NCP\n\n---\n\n## 😤 **The MCP Paradox: From Assistant to Desperate**\n\nYou gave your AI assistant 50 tools to be more capable. Instead, you got desperation:\n\n- **Paralyzed by choice** (\"Should I use `read_file` or `get_file_content`?\")\n- **Exhausted before starting** (\"I've spent my context limit analyzing which tool to use\")\n- **Costs explode** (50+ tool schemas burn tokens before any real work happens)\n- **Asks instead of acts** (used to be decisive, now constantly asks for clarification)\n\n---\n\n## 🧸 **Why Too Many Tools Break the System**\n\nThink about it like this:\n\n**A child with one toy** → Treasures it, masters it, creates endless games with it\n**A child with 50 toys** → Can't hold them all, gets overwhelmed, stops playing entirely\n\n**Your AI is that child.** MCPs are the toys. More isn't always better.\n\nThe most creative people thrive with **constraints**, not infinite options. A poet given \"write about anything\" faces writer's block. Given \"write a haiku about rain\"? Instant inspiration.\n\n**Your AI is the same.** Give it one perfect tool → Instant action. Give it 50 tools → Cognitive overload. NCP provides just-in-time tool discovery so your AI gets exactly what it needs, when it needs it.\n\n---\n\n## 📊 **The Before \u0026 After Reality**\n\n### **Before NCP: Desperate Assistant** 😵‍💫\n\nWhen your AI assistant manages 50 tools directly:\n\n```\n🤖 AI Assistant Context:\n├── Filesystem MCP (12 tools) ─ 15,000 tokens\n├── Database MCP (8 tools) ─── 12,000 tokens\n├── Web Search MCP (6 tools) ── 8,000 tokens\n├── Email MCP (15 tools) ───── 18,000 tokens\n├── Shell MCP (10 tools) ───── 14,000 tokens\n├── GitHub MCP (20 tools) ──── 25,000 tokens\n└── Slack MCP (9 tools) ────── 11,000 tokens\n\n💀 Total: 80 tools = 103,000 tokens of schemas\n```\n\n**What happens:**\n- AI burns 50%+ of context just understanding what tools exist\n- Spends 5-8 seconds analyzing which tool to use\n- Often picks wrong tool due to schema confusion\n- Hits context limits mid-conversation\n\n### **After NCP: Executive Assistant** ✨\n\nWith NCP as Chief of Staff:\n\n```\n🤖 AI Assistant Context:\n└── NCP (2 unified tools) ──── 2,500 tokens\n\n🎯 Behind the scenes: NCP manages all 80 tools\n📈 Context saved: 100,500 tokens (97% reduction!)\n⚡ Decision time: Sub-second tool selection\n🎪 AI behavior: Confident, focused, decisive\n```\n\n**Real results from our testing:**\n\n| Your MCP Setup | Without NCP | With NCP | Token Savings |\n|----------------|-------------|----------|---------------|\n| **Small** (5 MCPs, 25 tools) | 15,000 tokens | 8,000 tokens | **47% saved** |\n| **Medium** (15 MCPs, 75 tools) | 45,000 tokens | 12,000 tokens | **73% saved** |\n| **Large** (30 MCPs, 150 tools) | 90,000 tokens | 15,000 tokens | **83% saved** |\n| **Enterprise** (50+ MCPs, 250+ tools) | 150,000 tokens | 20,000 tokens | **87% saved** |\n\n**Translation:**\n- **5x faster responses** (8 seconds → 1.5 seconds)\n- **12x longer conversations** before hitting limits\n- **90% reduction** in wrong tool selection\n- **Zero context exhaustion** in typical sessions\n\n---\n\n## 📋 **Prerequisites**\n\n- **Node.js 18+** ([Download here](https://nodejs.org/))\n- **npm** (included with Node.js) or **npx** for running packages\n- **Command line access** (Terminal on Mac/Linux, Command Prompt/PowerShell on Windows)\n\n## 🚀 **Installation**\n\nChoose your MCP client for setup instructions:\n\n| Client | Description | Setup Guide |\n|--------|-------------|-------------|\n| **Claude Desktop** | Anthropic's official desktop app. **Best for NCP** - one-click .dxt install with auto-sync | **[→ Full Guide](docs/clients/claude-desktop.md)** |\n| **Claude Code** | Terminal-first AI workflow. Works out of the box! | Built-in support |\n| **VS Code** | GitHub Copilot with Agent Mode. Use NCP for semantic tool discovery | **[→ Setup](docs/clients/vscode.md)** |\n| **Cursor** | AI-first code editor with Composer. Popular VS Code alternative | **[→ Setup](docs/clients/cursor.md)** |\n| **Windsurf** | Codeium's AI-native IDE with Cascade. Built on VS Code | **[→ Setup](docs/clients/windsurf.md)** |\n| **Cline** | VS Code extension for AI-assisted development with MCP support | **[→ Setup](docs/clients/cline.md)** |\n| **Continue** | VS Code AI assistant with Agent Mode and local LLM support | **[→ Setup](docs/clients/continue.md)** |\n| **Want more clients?** | See the full list of MCP-compatible clients and tools | [Official MCP Clients](https://github.com/modelcontextprotocol/servers#clients) • [Awesome MCP](https://github.com/punkpeye/awesome-mcp) |\n| **Other Clients** | Any MCP-compatible client via npm | [Quick Start ↓](#quick-start-npm) |\n\n---\n\n### Quick Start (npm)\n\nFor advanced users or MCP clients not listed above:\n\n**Step 1: Install NCP**\n```bash\nnpm install -g @portel/ncp\n```\n\n**Step 2: Import existing MCPs (optional)**\n```bash\nncp config import  # Paste your config JSON when prompted\n```\n\n**Step 3: Configure your MCP client**\n\nAdd to your client's MCP configuration:\n```json\n{\n  \"mcpServers\": {\n    \"ncp\": {\n      \"command\": \"ncp\"\n    }\n  }\n}\n```\n\n**✅ Done!** Your AI now sees just 2 tools instead of 50+.\n\n![NCP List Overview](docs/images/ncp-list.png)\n\n---\n\n## 🧪 **Test Drive: See the Difference Yourself**\n\nWant to experience what your AI experiences? NCP has a human-friendly CLI:\n\n### **🔍 Smart Discovery**\n```bash\n# Ask like your AI would ask:\nncp find \"I need to read a file\"\nncp find \"help me send an email\"\nncp find \"search for something online\"\n```\n\n![NCP Find Command](docs/images/ncp-find.png)\n\n**Notice:** NCP understands intent, not just keywords. Just like your AI needs.\n\n### **📋 Ecosystem Overview**\n```bash\n# See your complete MCP ecosystem:\nncp list --depth 2\n\n# Get help anytime:\nncp --help\n```\n\n![NCP Help Command](docs/images/ncp-help.png)\n\n### **⚡ Direct Testing**\n```bash\n# Test any tool safely:\nncp run filesystem read_file --path \"/tmp/test.txt\"\n```\n\n**Why this matters:** You can debug and test tools directly, just like your AI would use them.\n\n### **✅ Verify Everything Works**\n\n```bash\n# 1. Check NCP is installed correctly\nncp --version\n\n# 2. Confirm your MCPs are imported\nncp list\n\n# 3. Test tool discovery\nncp find \"file\"\n\n# 4. Test a simple tool (if you have filesystem MCP)\nncp run filesystem read_file --path \"/tmp/test.txt\" --dry-run\n```\n\n**✅ Success indicators:**\n- NCP shows version number\n- `ncp list` shows your imported MCPs\n- `ncp find` returns relevant tools\n- Your AI client shows only NCP in its tool list\n\n---\n\n## 💪 **From Tools to Automation: The Real Power**\n\nYou've seen `find` (discover tools) and `code` (execute TypeScript). Individually, they're useful. **Together with scheduling, they become an automation powerhouse.**\n\n### A Real Example: The MCP Conference Scraper\n\nWe wanted to stay on top of MCP-related conferences and workshops for an upcoming release. Instead of manually checking websites daily, we asked Claude:\n\n\u003e \"Set up a daily scraper that finds MCP conferences and saves them to a CSV file\"\n\n**What Claude did:**\n\n1. **Used `code` to write the automation:**\n   ```typescript\n   // Search the web for MCP conferences\n   const results = await web.search({\n     query: \"Model Context Protocol conference 2025\"\n   });\n\n   // Read each result and extract details\n   for (const url of results) {\n     const content = await web.read({ url });\n     // Extract title, deadline, description...\n     // Save to ~/.ncp/mcp-conferences.csv\n   }\n   ```\n\n2. **Used `schedule` to automate it:**\n   ```bash\n   ncp schedule create code:run \"every day at 9am\" \\\n     --name \"MCP Conference Scraper\" \\\n     --catchup-missed\n   ```\n\n**How to set this up yourself:**\n\nFirst, install the web photon (provides search and read capabilities):\n```bash\n# Install from the official photons repo\nncp photon add https://raw.githubusercontent.com/portel-dev/photons/main/web.photon.ts\n```\n\nThen ask Claude to create the scraper - it will use the web photon automatically.\n\n**What happens now:**\n- Every morning at 9am, the scraper runs automatically\n- Searches for new MCP events and adds them to the CSV\n- If our laptop was closed at 9am, it catches up when we open it\n- We wake up to fresh conference data - no manual work\n\n**The insight:** `find` and `code` let AI write automation. `schedule` makes it run forever. That's the powerhouse.\n\n---\n\n## 💡 **Why NCP Transforms Your AI Experience**\n\n### **🧠 From Desperation to Delegation**\n- **Desperate Assistant:** \"I see 50 tools... which should I use... let me think...\"\n- **Executive Assistant:** \"I need file access. Done.\" *(NCP handles the details)*\n\n### **💰 Massive Token Savings**\n- **Before:** 100k+ tokens burned on tool confusion\n- **After:** 2.5k tokens for focused execution\n- **Result:** 40x token efficiency = 40x longer conversations\n\n### **🎯 Eliminates Choice Paralysis**\n- **Desperate:** AI freezes, picks wrong tool, asks for clarification\n- **Executive:** NCP's Chief of Staff finds the RIGHT tool instantly\n\n### **🚀 Confident Action**\n- **Before:** 8-second delays, hesitation, \"Which tool should I use?\"\n- **After:** Instant decisions, immediate execution, zero doubt\n\n**Bottom line:** Your AI goes from desperate assistant to **executive assistant**.\n\n---\n\n## ⚡ **Supercharged Features**\n\nHere's exactly how NCP empowers your MCPs:\n\n| Feature | What It Does | Why It Matters |\n|---------|-------------|----------------|\n| **🔍 Instant Tool Discovery** | Semantic search understands intent (\"read a file\") not just keywords | Your AI finds the RIGHT tool in \u003c1s instead of analyzing 50 schemas |\n| **📦 On-Demand Loading** | MCPs and tools load only when needed, not at startup | Saves 97% of context tokens - AI starts working immediately |\n| **⏰ Automated Scheduling** | Run any tool on cron schedules or natural language times | Background automation without keeping AI sessions open |\n| **🔌 Universal Compatibility** | Works with Claude Desktop, Claude Code, Cursor, VS Code, and any MCP client | One configuration for all your AI tools - no vendor lock-in |\n| **💾 Smart Caching** | Intelligent caching of tool schemas and responses | Eliminates redundant indexing - energy efficient and fast |\n\n**The result:** Your MCPs go from scattered tools to a **unified, intelligent system** that your AI can actually use effectively.\n\n---\n\n## 🛠️ **For Power Users: Manual Setup**\n\nPrefer to build from scratch? Add MCPs manually:\n\n```bash\n# Add the most popular MCPs:\n\n# AI reasoning and memory\nncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking\nncp add memory npx @modelcontextprotocol/server-memory\n\n# File and development tools\nncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents  # Path: directory to access\nncp add github npx @modelcontextprotocol/server-github                       # No path needed\n\n# Search and productivity\nncp add brave-search npx @modelcontextprotocol/server-brave-search           # No path needed\n```\n\n![NCP Add Command](docs/images/ncp-add.png)\n\n**💡 Pro tip:** Browse [Smithery.ai](https://smithery.ai) (2,200+ MCPs) or [mcp.so](https://mcp.so) to discover tools for your specific needs.\n\n---\n\n## 🎯 **Popular MCPs That Work Great with NCP**\n\n### **🔥 Most Downloaded**\n```bash\n# Community favorites (download counts from Smithery.ai):\nncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking  # 5,550+ downloads\nncp add memory npx @modelcontextprotocol/server-memory                            # 4,200+ downloads\nncp add brave-search npx @modelcontextprotocol/server-brave-search                # 680+ downloads\n```\n\n### **🛠️ Development Essentials**\n```bash\n# Popular dev tools:\nncp add filesystem npx @modelcontextprotocol/server-filesystem ~/code\nncp add github npx @modelcontextprotocol/server-github\nncp add shell npx @modelcontextprotocol/server-shell\n```\n\n### **🌐 Productivity \u0026 Integrations**\n```bash\n# Enterprise favorites:\nncp add gmail npx @mcptools/gmail-mcp\nncp add slack npx @modelcontextprotocol/server-slack\nncp add google-drive npx @modelcontextprotocol/server-gdrive\nncp add postgres npx @modelcontextprotocol/server-postgres\nncp add puppeteer npx @hisma/server-puppeteer\n```\n\n\n## 🤖 **Internal MCPs**\n\nNCP includes powerful internal MCPs that extend functionality beyond external tool orchestration:\n\n### **Scheduler MCP** - Automate Any Tool\nSchedule any MCP tool to run automatically using cron or natural language schedules.\n\n```bash\n# Schedule a daily backup check\nncp run schedule:create --params '{\n  \"name\": \"Daily Backup\",\n  \"schedule\": \"every day at 2am\",\n  \"tool\": \"filesystem:list_directory\",\n  \"parameters\": {\"path\": \"/backups\"}\n}'\n```\n\n**Features:**\n- ✅ Natural language schedules (\"every day at 9am\", \"every monday\")\n- ✅ Standard cron expressions for advanced control\n- ✅ Automatic validation before scheduling\n- ✅ Execution history and monitoring\n- ✅ Works even when NCP is not running (system cron integration)\n\n**[→ Full Scheduler Guide](docs/SCHEDULER_USER_GUIDE.md)**\n\n### **MCP Management MCP** - Install MCPs from AI\nInstall and configure MCPs dynamically through natural language.\n\n```bash\n# AI can discover and install MCPs for you\nncp find \"install mcp\"\n# Shows: mcp:add, mcp:remove, mcp:list\n```\n\n**Features:**\n- ✅ Search and discover MCPs from registries\n- ✅ Install MCPs without manual configuration\n- ✅ Update and remove MCPs programmatically\n- ✅ AI can self-extend with new capabilities\n\n### **Skills Management MCP** - Extend Claude with Plugins\n\nManage Anthropic Agent Skills - modular extensions that add specialized knowledge and tools to Claude.\n\n```typescript\n// Discover skills using vector search\nconst results = await skills.find({ query: \"canvas design\" });\n\n// Install a skill\nawait skills.add({ skill_name: \"canvas-design\" });\n\n// List installed skills\nconst installed = await skills.list();\n\n// Read skill resources\nconst template = await skills.read_resource({\n  skill_name: \"canvas-design\",\n  file_path: \"resources/templates.md\"\n});\n```\n\n**Features:**\n- ✅ Vector-powered semantic search for skills\n- ✅ One-command install from official marketplace\n- ✅ Progressive disclosure (metadata → full content → resources)\n- ✅ Official Anthropic marketplace integration\n- ✅ Custom marketplace support\n- ✅ Auto-loading of installed skills\n\n**[→ Full Skills Guide](./SKILLS.md)**\n\n### **Analytics MCP** - Visualize Usage \u0026 Performance\nView usage statistics, token savings, and performance metrics directly in your chat.\n\n```bash\n# View usage overview with ASCII charts\nncp run analytics:overview --params '{\"period\": 7}'\n```\n\n**Features:**\n- ✅ Usage trends and most used tools\n- ✅ Token savings analysis (Code-Mode efficiency)\n- ✅ Performance metrics (response times, error rates)\n- ✅ ASCII-formatted charts for AI consumption\n\n**Configuration:**\nInternal MCPs are disabled by default. Enable in your profile settings:\n\n```json\n{\n  \"settings\": {\n    \"enable_schedule_mcp\": true,\n    \"enable_mcp_management\": true,\n    \"enable_skills\": true,\n    \"enable_analytics_mcp\": true\n  }\n}\n```\n\n---\n\n## 🔧 **Advanced Features**\n\n### **Smart Health Monitoring**\nNCP automatically detects broken MCPs and routes around them:\n\n```bash\nncp list --depth 1    # See health status\nncp config validate   # Check configuration health\n```\n\n**🎯 Result:** Your AI never gets stuck on broken tools.\n\n### **Multi-Profile Organization**\nOrganize MCPs by project or environment:\n\n```bash\n# Development setup\nncp add --profile dev filesystem npx @modelcontextprotocol/server-filesystem ~/dev\n\n# Production setup\nncp add --profile prod database npx production-db-server\n\n# Use specific profile\nncp --profile dev find \"file tools\"\n```\n\n### **🚀 Project-Level Configuration**\n**New:** Configure MCPs per project with automatic detection - perfect for teams and Cloud IDEs:\n\n```bash\n# In any project directory, create local MCP configuration:\nmkdir .ncp\nncp add filesystem npx @modelcontextprotocol/server-filesystem ./\nncp add github npx @modelcontextprotocol/server-github\n\n# NCP automatically detects and uses project-local configuration\nncp find \"save file\"  # Uses only project MCPs\n```\n\n**How it works:**\n- 📁 **Local `.ncp` directory exists** → Uses project configuration\n- 🏠 **No local `.ncp` directory** → Falls back to global `~/.ncp`\n- 🎯 **Zero profile management needed** → Everything goes to default `all.json`\n\n**Perfect for:**\n- 🤖 **Claude Code projects** (project-specific MCP tooling)\n- 👥 **Team consistency** (ship `.ncp` folder with your repo)\n- 🔧 **Project-specific tooling** (each project defines its own MCPs)\n- 📦 **Environment isolation** (no global MCP conflicts)\n\n```bash\n# Example project structures:\nfrontend-app/\n  .ncp/profiles/all.json   # → playwright, lighthouse, browser-context\n  src/\n\napi-backend/\n  .ncp/profiles/all.json   # → postgres, redis, docker, kubernetes\n  server/\n```\n\n### **HTTP/SSE Transport \u0026 Hibernation Support**\n\nNCP supports both **stdio** (local) and **HTTP/SSE** (remote) MCP servers:\n\n**Stdio Transport** (Traditional):\n```bash\n# Local MCP servers running as processes\nncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents\n```\n\n**HTTP/SSE Transport** (Remote):\n```json\n{\n  \"mcpServers\": {\n    \"remote-mcp\": {\n      \"url\": \"https://mcp.example.com/api\",\n      \"auth\": {\n        \"type\": \"bearer\",\n        \"token\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\n**OAuth 2.1 with PKCE** (MCP 2025-03-26 spec):\n```json\n{\n  \"mcpServers\": {\n    \"oauth-mcp\": {\n      \"url\": \"https://mcp.example.com/api\",\n      \"auth\": {\n        \"type\": \"oauth\",\n        \"oauth21\": {\n          \"scopes\": [\"read\", \"write\"],\n          \"callbackPort\": 9876,\n          \"clientId\": \"optional-pre-registered-client-id\",\n          \"clientSecret\": \"optional-client-secret\"\n        }\n      }\n    }\n  }\n}\n```\n\n**OAuth 2.1 Features:**\n- ✅ **PKCE (Proof Key for Code Exchange)** - Required by OAuth 2.1 for security\n- ✅ **Dynamic Client Registration (RFC 7591)** - Auto-registers if no clientId provided\n- ✅ **Token Storage \u0026 Auto-Refresh** - Tokens saved to `~/.ncp/auth/` and refreshed automatically\n- ✅ **Browser Authorization Flow** - Opens browser for user consent\n- ✅ **Headless Fallback** - Manual code entry for servers/CI environments\n- ✅ **Protected Resource Discovery (RFC 9728)** - Auto-discovers OAuth endpoints\n\n**First-time setup flow:**\n1. NCP opens browser to authorization URL\n2. You grant permissions\n3. Browser redirects to local callback (`http://localhost:9876`)\n4. NCP exchanges code for access token (with PKCE)\n5. Token saved and refreshed automatically for future requests\n\n**🔋 Hibernation-Enabled Servers:**\n\nNCP automatically supports hibernation-enabled MCP servers (like Cloudflare Durable Objects or Metorial):\n- **Zero configuration needed** - Hibernation works transparently\n- **Automatic wake-up** - Server wakes on demand when NCP makes requests\n- **State preservation** - Server state is maintained across hibernation cycles\n- **Cost savings** - Only pay when MCPs are actively processing requests\n\n**How it works:**\n1. Server hibernates when idle (consumes zero resources)\n2. NCP sends a request → Server wakes instantly\n3. Server processes request and responds\n4. Server returns to hibernation after idle timeout\n\n**Perfect for:**\n- 💰 **Cost optimization** - Only pay for active processing time\n- 🌐 **Cloud-hosted MCPs** - Metorial, Cloudflare Workers, serverless platforms\n- ♻️ **Resource efficiency** - No idle server costs\n- 🚀 **Scale to zero** - Servers automatically sleep when not needed\n\n\u003e **Note:** Hibernation is a server-side feature. NCP's standard HTTP/SSE client automatically works with both traditional and hibernation-enabled servers without any special configuration.\n\n### **Photon Runtime (CLI vs DXT)**\n\nThe TypeScript Photon runtime is enabled by default, but the toggle lives in different places depending on how you run NCP:\n\n- **CLI / npm installs:** Edit `~/.ncp/settings.json` (or run `ncp config`) and set `enablePhotonRuntime: true` or `false`. You can also override ad‑hoc with `NCP_ENABLE_PHOTON_RUNTIME=true ncp find \"photon\"`.\n- **DXT / client bundles (Claude Desktop, Cursor, etc.):** These builds **ignore** `~/.ncp/settings.json`. Configure photons by setting the env var inside the client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"ncp\": {\n      \"command\": \"ncp\",\n      \"env\": {\n        \"NCP_ENABLE_PHOTON_RUNTIME\": \"true\"\n      }\n    }\n  }\n}\n```\n\nIf you disable the photon runtime, internal MCPs continue to work, but `.photon.ts` files are ignored until you re-enable the flag.\n\n### **Import from Anywhere**\n```bash\n# From clipboard (any JSON config)\nncp config import\n\n# From specific file\nncp config import \"~/my-mcp-config.json\"\n\n# From Claude Desktop (auto-detected paths)\nncp config import\n```\n\n---\n\n## 🛟 **Troubleshooting**\n\n### **Import Issues**\n```bash\n# Check what was imported\nncp list\n\n# Validate health of imported MCPs\nncp config validate\n\n# See detailed import logs\nDEBUG=ncp:* ncp config import\n```\n\n### **AI Not Using Tools**\n- **Check connection:** `ncp list` (should show your MCPs)\n- **Test discovery:** `ncp find \"your query\"`\n- **Validate config:** Ensure your AI client points to `ncp` command\n\n### **Performance Issues**\n```bash\n# Check MCP health (unhealthy MCPs slow everything down)\nncp list --depth 1\n\n# Clear cache if needed\nrm -rf ~/.ncp/cache\n\n# Monitor with debug logs\nDEBUG=ncp:* ncp find \"test\"\n```\n\n---\n\n## 🌓 **Why We Built This**\n\n**Like Yin and Yang, everything relies on the balance of things.**\n\n**Compute** gives us precision and certainty.\n**AI** gives us creativity and probability.\n\nWe believe breakthrough products emerge when you combine these forces in the right ratio.\n\n**How NCP embodies this balance:**\n\n| What NCP Does | AI (Creativity) | Compute (Precision) | The Balance |\n|---------------|-----------------|---------------------|-------------|\n| **Tool Discovery** | Understands \"read a file\" semantically | Routes to exact tool deterministically | Natural request → Precise execution |\n| **Orchestration** | Flexible to your intent | Reliable tool execution | Natural flow → Certain outcomes |\n| **Health Monitoring** | Adapts to patterns | Monitors connections, auto-failover | Smart adaptation → Reliable uptime |\n\nNeither pure AI (too unpredictable) nor pure compute (too rigid).\n\nYour AI stays creative. NCP handles the precision.\n\n---\n\n## 📚 **Deep Dive: How It Works**\n\nWant the technical details? Token analysis, architecture diagrams, and performance benchmarks:\n\n📖 **[Read the Technical Guide →](HOW-IT-WORKS.md)**\n\nLearn about:\n- Vector similarity search algorithms\n- N-to-1 orchestration architecture\n- Real-world token usage comparisons\n- Health monitoring and failover systems\n\n---\n\n## 🤝 **Contributing**\n\nHelp make NCP even better:\n\n- 🐛 **Bug reports:** [GitHub Issues](https://github.com/portel-dev/ncp/issues)\n- 💡 **Feature requests:** [GitHub Discussions](https://github.com/portel-dev/ncp/discussions)\n- 🔄 **Pull requests:** [Contributing Guide](CONTRIBUTING.md)\n\n---\n\n## 📄 **License**\n\nElastic License 2.0 - [Full License](LICENSE)\n\n**TLDR:** Free for all use including commercial. Cannot be offered as a hosted service to third parties.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportel-dev%2Fncp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fportel-dev%2Fncp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportel-dev%2Fncp/lists"}