This is page 2 of 9. Use http://codebase.md/portel-dev/ncp?lines=false&page={x} to view the full context.
# Directory Structure
```
├── .dockerignore
├── .dxtignore
├── .github
│ ├── FEATURE_STORY_TEMPLATE.md
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.yml
│ │ ├── config.yml
│ │ ├── feature_request.yml
│ │ └── mcp_server_request.yml
│ ├── pull_request_template.md
│ └── workflows
│ ├── ci.yml
│ ├── publish-mcp-registry.yml
│ └── release.yml
├── .gitignore
├── .mcpbignore
├── .npmignore
├── .release-it.json
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── COMPLETE-IMPLEMENTATION-SUMMARY.md
├── CONTRIBUTING.md
├── CRITICAL-ISSUES-FOUND.md
├── docs
│ ├── clients
│ │ ├── claude-desktop.md
│ │ ├── cline.md
│ │ ├── continue.md
│ │ ├── cursor.md
│ │ ├── perplexity.md
│ │ └── README.md
│ ├── download-stats.md
│ ├── guides
│ │ ├── clipboard-security-pattern.md
│ │ ├── how-it-works.md
│ │ ├── mcp-prompts-for-user-interaction.md
│ │ ├── mcpb-installation.md
│ │ ├── ncp-registry-command.md
│ │ ├── pre-release-checklist.md
│ │ ├── telemetry-design.md
│ │ └── testing.md
│ ├── images
│ │ ├── ncp-add.png
│ │ ├── ncp-find.png
│ │ ├── ncp-help.png
│ │ ├── ncp-import.png
│ │ ├── ncp-list.png
│ │ └── ncp-transformation-flow.png
│ ├── mcp-registry-setup.md
│ ├── pr-schema-additions.ts
│ └── stories
│ ├── 01-dream-and-discover.md
│ ├── 02-secrets-in-plain-sight.md
│ ├── 03-sync-and-forget.md
│ ├── 04-double-click-install.md
│ ├── 05-runtime-detective.md
│ └── 06-official-registry.md
├── DYNAMIC-RUNTIME-SUMMARY.md
├── EXTENSION-CONFIG-DISCOVERY.md
├── INSTALL-EXTENSION.md
├── INTERNAL-MCP-ARCHITECTURE.md
├── jest.config.js
├── LICENSE
├── MANAGEMENT-TOOLS-COMPLETE.md
├── manifest.json
├── manifest.json.backup
├── MCP-CONFIG-SCHEMA-IMPLEMENTATION-EXAMPLE.ts
├── MCP-CONFIG-SCHEMA-SIMPLE-EXAMPLE.json
├── MCP-CONFIGURATION-SCHEMA-FORMAT.json
├── MCPB-ARCHITECTURE-DECISION.md
├── NCP-EXTENSION-COMPLETE.md
├── package-lock.json
├── package.json
├── parity-between-cli-and-mcp.txt
├── PROMPTS-IMPLEMENTATION.md
├── README-COMPARISON.md
├── README.md
├── README.new.md
├── REGISTRY-INTEGRATION-COMPLETE.md
├── RELEASE-PROCESS-IMPROVEMENTS.md
├── RELEASE-SUMMARY.md
├── RELEASE.md
├── RUNTIME-DETECTION-COMPLETE.md
├── scripts
│ ├── cleanup
│ │ └── scan-repository.js
│ └── sync-server-version.cjs
├── SECURITY.md
├── server.json
├── src
│ ├── analytics
│ │ ├── analytics-formatter.ts
│ │ ├── log-parser.ts
│ │ └── visual-formatter.ts
│ ├── auth
│ │ ├── oauth-device-flow.ts
│ │ └── token-store.ts
│ ├── cache
│ │ ├── cache-patcher.ts
│ │ ├── csv-cache.ts
│ │ └── schema-cache.ts
│ ├── cli
│ │ └── index.ts
│ ├── discovery
│ │ ├── engine.ts
│ │ ├── mcp-domain-analyzer.ts
│ │ ├── rag-engine.ts
│ │ ├── search-enhancer.ts
│ │ └── semantic-enhancement-engine.ts
│ ├── extension
│ │ └── extension-init.ts
│ ├── index-mcp.ts
│ ├── index.ts
│ ├── internal-mcps
│ │ ├── internal-mcp-manager.ts
│ │ ├── ncp-management.ts
│ │ └── types.ts
│ ├── orchestrator
│ │ └── ncp-orchestrator.ts
│ ├── profiles
│ │ └── profile-manager.ts
│ ├── server
│ │ ├── mcp-prompts.ts
│ │ └── mcp-server.ts
│ ├── services
│ │ ├── config-prompter.ts
│ │ ├── config-schema-reader.ts
│ │ ├── error-handler.ts
│ │ ├── output-formatter.ts
│ │ ├── registry-client.ts
│ │ ├── tool-context-resolver.ts
│ │ ├── tool-finder.ts
│ │ ├── tool-schema-parser.ts
│ │ └── usage-tips-generator.ts
│ ├── testing
│ │ ├── create-real-mcp-definitions.ts
│ │ ├── dummy-mcp-server.ts
│ │ ├── mcp-definitions.json
│ │ ├── real-mcp-analyzer.ts
│ │ ├── real-mcp-definitions.json
│ │ ├── real-mcps.csv
│ │ ├── setup-dummy-mcps.ts
│ │ ├── setup-tiered-profiles.ts
│ │ ├── test-profile.json
│ │ ├── test-semantic-enhancement.ts
│ │ └── verify-profile-scaling.ts
│ ├── transports
│ │ └── filtered-stdio-transport.ts
│ └── utils
│ ├── claude-desktop-importer.ts
│ ├── client-importer.ts
│ ├── client-registry.ts
│ ├── config-manager.ts
│ ├── health-monitor.ts
│ ├── highlighting.ts
│ ├── logger.ts
│ ├── markdown-renderer.ts
│ ├── mcp-error-parser.ts
│ ├── mcp-wrapper.ts
│ ├── ncp-paths.ts
│ ├── parameter-prompter.ts
│ ├── paths.ts
│ ├── progress-spinner.ts
│ ├── response-formatter.ts
│ ├── runtime-detector.ts
│ ├── schema-examples.ts
│ ├── security.ts
│ ├── text-utils.ts
│ ├── update-checker.ts
│ ├── updater.ts
│ └── version.ts
├── STORY-DRIVEN-DOCUMENTATION.md
├── STORY-FIRST-WORKFLOW.md
├── test
│ ├── __mocks__
│ │ ├── chalk.js
│ │ ├── transformers.js
│ │ ├── updater.js
│ │ └── version.ts
│ ├── cache-loading-focused.test.ts
│ ├── cache-optimization.test.ts
│ ├── cli-help-validation.sh
│ ├── coverage-boost.test.ts
│ ├── curated-ecosystem-validation.test.ts
│ ├── discovery-engine.test.ts
│ ├── discovery-fallback-focused.test.ts
│ ├── ecosystem-discovery-focused.test.ts
│ ├── ecosystem-discovery-validation-simple.test.ts
│ ├── final-80-percent-push.test.ts
│ ├── final-coverage-push.test.ts
│ ├── health-integration.test.ts
│ ├── health-monitor.test.ts
│ ├── helpers
│ │ └── mock-server-manager.ts
│ ├── integration
│ │ └── mcp-client-simulation.test.cjs
│ ├── logger.test.ts
│ ├── mcp-ecosystem-discovery.test.ts
│ ├── mcp-error-parser.test.ts
│ ├── mcp-immediate-response-check.js
│ ├── mcp-server-protocol.test.ts
│ ├── mcp-timeout-scenarios.test.ts
│ ├── mcp-wrapper.test.ts
│ ├── mock-mcps
│ │ ├── aws-server.js
│ │ ├── base-mock-server.mjs
│ │ ├── brave-search-server.js
│ │ ├── docker-server.js
│ │ ├── filesystem-server.js
│ │ ├── git-server.mjs
│ │ ├── github-server.js
│ │ ├── neo4j-server.js
│ │ ├── notion-server.js
│ │ ├── playwright-server.js
│ │ ├── postgres-server.js
│ │ ├── shell-server.js
│ │ ├── slack-server.js
│ │ └── stripe-server.js
│ ├── mock-smithery-mcp
│ │ ├── index.js
│ │ ├── package.json
│ │ └── smithery.yaml
│ ├── ncp-orchestrator.test.ts
│ ├── orchestrator-health-integration.test.ts
│ ├── orchestrator-simple-branches.test.ts
│ ├── performance-benchmark.test.ts
│ ├── quick-coverage.test.ts
│ ├── rag-engine.test.ts
│ ├── regression-snapshot.test.ts
│ ├── search-enhancer.test.ts
│ ├── session-id-passthrough.test.ts
│ ├── setup.ts
│ ├── tool-context-resolver.test.ts
│ ├── tool-schema-parser.test.ts
│ ├── user-story-discovery.test.ts
│ └── version-util.test.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/test/mcp-immediate-response-check.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Test MCP Server Immediate Response
*
* Verifies that NCP MCP server:
* 1. Responds to initialize immediately
* 2. Responds to tools/list immediately (without waiting for indexing)
* 3. Advertises 'find' and 'run' tools
* 4. Does not block on indexing
*/
import { MCPServer } from '../dist/server/mcp-server.js';
async function testMCPImmediateResponse() {
console.log('========================================');
console.log('Testing MCP Server Immediate Response');
console.log('========================================\n');
const server = new MCPServer('default', false, false); // No progress output
// Test 1: Initialize should return immediately
console.log('Test 1: Initialize returns immediately');
console.log('----------------------------------------');
const initStartTime = Date.now();
await server.initialize();
const initDuration = Date.now() - initStartTime;
if (initDuration < 100) {
console.log(`✓ PASS: Initialize returned in ${initDuration}ms (non-blocking)`);
} else {
console.log(`✗ FAIL: Initialize took ${initDuration}ms (should be < 100ms)`);
}
console.log('');
// Test 2: tools/list should return immediately
console.log('Test 2: tools/list returns immediately (even during indexing)');
console.log('----------------------------------------');
const listStartTime = Date.now();
const toolsResponse = await server.handleRequest({
jsonrpc: '2.0',
id: 1,
method: 'tools/list'
});
const listDuration = Date.now() - listStartTime;
if (listDuration < 100) {
console.log(`✓ PASS: tools/list returned in ${listDuration}ms (non-blocking)`);
} else {
console.log(`✗ FAIL: tools/list took ${listDuration}ms (should be < 100ms)`);
}
console.log('');
// Test 3: Verify tools are advertised
console.log('Test 3: Advertises find and run tools');
console.log('----------------------------------------');
const tools = toolsResponse.result?.tools || [];
const toolNames = tools.map(t => t.name);
console.log(`Found ${tools.length} tools: ${toolNames.join(', ')}`);
if (toolNames.includes('find')) {
console.log('✓ PASS: find tool advertised');
} else {
console.log('✗ FAIL: find tool NOT advertised');
}
if (toolNames.includes('run')) {
console.log('✓ PASS: run tool advertised');
} else {
console.log('✗ FAIL: run tool NOT advertised');
}
console.log('');
// Test 4: Initialize request returns immediately
console.log('Test 4: Initialize request returns immediately');
console.log('----------------------------------------');
const initReqStartTime = Date.now();
const initResponse = await server.handleRequest({
jsonrpc: '2.0',
id: 2,
method: 'initialize',
params: {
protocolVersion: '2024-11-05',
capabilities: {},
clientInfo: { name: 'test-client', version: '1.0.0' }
}
});
const initReqDuration = Date.now() - initReqStartTime;
if (initReqDuration < 50) {
console.log(`✓ PASS: Initialize request returned in ${initReqDuration}ms`);
} else {
console.log(`✗ FAIL: Initialize request took ${initReqDuration}ms (should be < 50ms)`);
}
if (initResponse.result?.protocolVersion) {
console.log(`✓ PASS: Initialize returned protocol version ${initResponse.result.protocolVersion}`);
} else {
console.log('✗ FAIL: Initialize did not return protocol version');
}
console.log('');
await server.cleanup();
console.log('========================================');
console.log('Test Summary');
console.log('========================================');
console.log('Expected behavior:');
console.log(' - initialize() returns immediately (< 100ms)');
console.log(' - tools/list returns immediately (< 100ms)');
console.log(' - Advertises find and run tools');
console.log(' - Indexing happens in background');
}
testMCPImmediateResponse().catch(error => {
console.error('Test failed with error:', error);
process.exit(1);
});
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "@portel/ncp",
"version": "1.5.2",
"mcpName": "io.github.portel-dev/ncp",
"description": "Natural Context Provider - N-to-1 MCP Orchestration for AI Assistants",
"main": "dist/index.js",
"module": "dist/index.js",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"bin": {
"ncp": "dist/index.js"
},
"type": "module",
"scripts": {
"build": "tsc && chmod +x dist/index.js",
"postinstall": "npm run build:if-dev",
"build:if-dev": "[ -d node_modules/typescript ] && npm run build || echo 'Build skipped (production install)'",
"start": "node dist/index.js",
"dev": "npm run build && npm run start",
"test": "jest --detectOpenHandles --forceExit",
"test:coverage": "jest --coverage --detectOpenHandles --forceExit",
"test:watch": "jest --watch",
"test:critical": "jest test/mcp-server-protocol.test.ts test/mcp-timeout-scenarios.test.ts --verbose --detectOpenHandles --forceExit",
"test:integration": "npm run build && node test/integration/mcp-client-simulation.test.cjs",
"test:cli": "bash test/cli-help-validation.sh",
"test:pre-publish": "npm run test:critical && npm run test:integration",
"test:package": "node scripts/test-package-locally.cjs",
"build:dxt": "npm run build && npm prune --production && npx @anthropic-ai/mcpb pack && npm run rename:dxt && npm install",
"rename:dxt": "for f in *.mcpb; do [ -f \"$f\" ] && mv \"$f\" \"${f%.mcpb}.dxt\" || true; done",
"stats": "node scripts/check-dxt-downloads.js",
"prepack": "npm run build && npm run test:pre-publish",
"prepublishOnly": "npm run build && npm run test:pre-publish && node scripts/sync-server-version.cjs",
"release": "release-it",
"release:dry": "release-it --dry-run"
},
"keywords": [
"mcp",
"model-context-protocol",
"ai-orchestration",
"tool-discovery"
],
"author": "Portel",
"license": "Elastic-2.0",
"repository": {
"type": "git",
"url": "git+https://github.com/portel-dev/ncp.git"
},
"homepage": "https://github.com/portel-dev/ncp#readme",
"bugs": {
"url": "https://github.com/portel-dev/ncp/issues"
},
"types": "dist/index.d.ts",
"engines": {
"node": ">=18.0.0"
},
"files": [
"dist",
"LICENSE",
"README.md",
"server.json",
"package.json"
],
"files:comments": "Explicit list of files to include in the package",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.18.0",
"@types/prompts": "^2.4.9",
"@xenova/transformers": "^2.17.2",
"asciichart": "^1.5.25",
"chalk": "^5.3.0",
"cli-graph": "^3.2.2",
"cli-highlight": "^2.1.11",
"clipboardy": "^4.0.0",
"commander": "^14.0.1",
"env-paths": "^3.0.0",
"json-colorizer": "^3.0.1",
"marked": "^15.0.12",
"marked-terminal": "^7.3.0",
"prettyjson": "^1.2.5",
"prompts": "^2.4.2",
"yaml": "^2.8.1"
},
"devDependencies": {
"@agent-infra/mcp-server-browser": "^1.2.23",
"@amap/amap-maps-mcp-server": "^0.0.8",
"@anthropic-ai/mcpb": "^1.1.1",
"@apify/actors-mcp-server": "^0.4.15",
"@benborla29/mcp-server-mysql": "^2.0.5",
"@currents/mcp": "^2.0.0",
"@heroku/mcp-server": "^1.0.7",
"@hubspot/mcp-server": "^0.4.0",
"@modelcontextprotocol/server-filesystem": "^2025.8.21",
"@modelcontextprotocol/server-sequential-thinking": "^2025.7.1",
"@notionhq/notion-mcp-server": "^1.9.0",
"@release-it/conventional-changelog": "^10.0.1",
"@supabase/mcp-server-supabase": "^0.5.5",
"@types/express": "^5.0.3",
"@types/jest": "^30.0.0",
"@types/marked-terminal": "^6.1.1",
"@types/node": "^20.0.0",
"@types/prettyjson": "^0.0.33",
"@upstash/context7-mcp": "^1.0.17",
"@winor30/mcp-server-datadog": "^1.6.0",
"jest": "^30.1.3",
"mcp-hello-world": "^1.1.2",
"mcp-server": "^0.0.9",
"mcp-server-kubernetes": "^2.9.6",
"release-it": "^19.0.4",
"ts-jest": "^29.4.2",
"tsx": "^4.20.5",
"typescript": "^5.0.0"
}
}
```
--------------------------------------------------------------------------------
/test/mock-mcps/shell-server.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Mock Shell MCP Server
* Real MCP server structure for shell command execution testing
*/
import { MockMCPServer } from './base-mock-server.js';
const serverInfo = {
name: 'shell-test',
version: '1.0.0',
description: 'Execute shell commands and system operations including scripts, processes, and system management'
};
const tools = [
{
name: 'execute_command',
description: 'Execute shell commands and system operations. Run scripts, manage processes, perform system tasks.',
inputSchema: {
type: 'object',
properties: {
command: {
type: 'string',
description: 'Shell command to execute'
},
working_directory: {
type: 'string',
description: 'Working directory for command execution'
},
timeout: {
type: 'number',
description: 'Command timeout in seconds'
},
environment: {
type: 'object',
description: 'Environment variables for command'
},
capture_output: {
type: 'boolean',
description: 'Capture command output'
}
},
required: ['command']
}
},
{
name: 'run_script',
description: 'Execute shell scripts and batch operations with parameters. Run automation scripts, execute batch jobs.',
inputSchema: {
type: 'object',
properties: {
script_path: {
type: 'string',
description: 'Path to script file'
},
arguments: {
type: 'array',
description: 'Script arguments',
items: { type: 'string' }
},
interpreter: {
type: 'string',
description: 'Script interpreter (bash, python, node, etc.)'
},
working_directory: {
type: 'string',
description: 'Working directory for script'
}
},
required: ['script_path']
}
},
{
name: 'manage_process',
description: 'Manage system processes including start, stop, and monitoring. Control services, manage applications.',
inputSchema: {
type: 'object',
properties: {
action: {
type: 'string',
description: 'Process action (start, stop, restart, status, list)'
},
process_name: {
type: 'string',
description: 'Process or service name'
},
pid: {
type: 'number',
description: 'Process ID for specific process operations'
},
signal: {
type: 'string',
description: 'Signal to send to process (TERM, KILL, etc.)'
}
},
required: ['action']
}
},
{
name: 'check_system_info',
description: 'Get system information including resources, processes, and status. Monitor system health, check resources.',
inputSchema: {
type: 'object',
properties: {
info_type: {
type: 'string',
description: 'Type of system info (cpu, memory, disk, network, processes)'
},
detailed: {
type: 'boolean',
description: 'Include detailed information'
}
},
required: ['info_type']
}
},
{
name: 'manage_environment',
description: 'Manage environment variables and system configuration. Set variables, configure system settings.',
inputSchema: {
type: 'object',
properties: {
action: {
type: 'string',
description: 'Environment action (get, set, unset, list)'
},
variable: {
type: 'string',
description: 'Environment variable name'
},
value: {
type: 'string',
description: 'Variable value for set action'
},
scope: {
type: 'string',
description: 'Variable scope (session, user, system)'
}
},
required: ['action']
}
}
];
// Create and run the server
const server = new MockMCPServer(serverInfo, tools);
server.run().catch(console.error);
```
--------------------------------------------------------------------------------
/test/mock-mcps/brave-search-server.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Mock Brave Search MCP Server
* Real MCP server structure for Brave Search API testing
*/
import { MockMCPServer } from './base-mock-server.js';
const serverInfo = {
name: 'brave-search-test',
version: '1.0.0',
description: 'Web search capabilities with privacy-focused results and real-time information'
};
const tools = [
{
name: 'web_search',
description: 'Search the web using Brave Search API with privacy protection. Find information, research topics, get current data.',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Search query string'
},
count: {
type: 'number',
description: 'Number of results to return'
},
offset: {
type: 'number',
description: 'Result offset for pagination'
},
country: {
type: 'string',
description: 'Country code for localized results'
},
search_lang: {
type: 'string',
description: 'Search language code'
},
ui_lang: {
type: 'string',
description: 'UI language code'
},
freshness: {
type: 'string',
description: 'Result freshness (pd, pw, pm, py for past day/week/month/year)'
}
},
required: ['query']
}
},
{
name: 'news_search',
description: 'Search for news articles with current events and breaking news. Get latest news, find articles, track stories.',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'News search query'
},
count: {
type: 'number',
description: 'Number of news results'
},
offset: {
type: 'number',
description: 'Result offset'
},
freshness: {
type: 'string',
description: 'News freshness filter'
},
text_decorations: {
type: 'boolean',
description: 'Include text decorations in results'
}
},
required: ['query']
}
},
{
name: 'image_search',
description: 'Search for images with filtering options. Find pictures, locate visual content, discover graphics.',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Image search query'
},
count: {
type: 'number',
description: 'Number of image results'
},
offset: {
type: 'number',
description: 'Result offset'
},
size: {
type: 'string',
description: 'Image size filter (small, medium, large, wallpaper)'
},
color: {
type: 'string',
description: 'Color filter'
},
type: {
type: 'string',
description: 'Image type (photo, clipart, lineart, animated)'
},
layout: {
type: 'string',
description: 'Image layout (square, wide, tall)'
}
},
required: ['query']
}
},
{
name: 'video_search',
description: 'Search for videos across platforms with filtering capabilities. Find educational content, tutorials, entertainment.',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Video search query'
},
count: {
type: 'number',
description: 'Number of video results'
},
offset: {
type: 'number',
description: 'Result offset'
},
duration: {
type: 'string',
description: 'Video duration filter (short, medium, long)'
},
resolution: {
type: 'string',
description: 'Video resolution filter'
}
},
required: ['query']
}
}
];
// Create and run the server
const server = new MockMCPServer(serverInfo, tools);
server.run().catch(console.error);
```
--------------------------------------------------------------------------------
/test/mock-mcps/docker-server.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Mock Docker MCP Server
* Real MCP server structure for Docker container management testing
*/
import { MockMCPServer } from './base-mock-server.js';
const serverInfo = {
name: 'docker-test',
version: '1.0.0',
description: 'Container management including Docker operations, image building, and deployment'
};
const tools = [
{
name: 'run_container',
description: 'Run Docker containers from images with configuration options. Deploy applications, start services.',
inputSchema: {
type: 'object',
properties: {
image: {
type: 'string',
description: 'Docker image name and tag'
},
name: {
type: 'string',
description: 'Container name'
},
ports: {
type: 'array',
description: 'Port mappings (host:container)',
items: { type: 'string' }
},
volumes: {
type: 'array',
description: 'Volume mappings',
items: { type: 'string' }
},
environment: {
type: 'object',
description: 'Environment variables'
},
detached: {
type: 'boolean',
description: 'Run container in background'
}
},
required: ['image']
}
},
{
name: 'build_image',
description: 'Build Docker images from Dockerfile with build context. Create custom images, package applications.',
inputSchema: {
type: 'object',
properties: {
dockerfile_path: {
type: 'string',
description: 'Path to Dockerfile'
},
context_path: {
type: 'string',
description: 'Build context directory'
},
tag: {
type: 'string',
description: 'Image tag name'
},
build_args: {
type: 'object',
description: 'Build arguments'
},
no_cache: {
type: 'boolean',
description: 'Build without cache'
}
},
required: ['dockerfile_path', 'tag']
}
},
{
name: 'manage_container',
description: 'Manage Docker container lifecycle including start, stop, restart operations. Control running containers.',
inputSchema: {
type: 'object',
properties: {
action: {
type: 'string',
description: 'Container action (start, stop, restart, remove, pause, unpause)'
},
container: {
type: 'string',
description: 'Container name or ID'
},
force: {
type: 'boolean',
description: 'Force action if needed'
}
},
required: ['action', 'container']
}
},
{
name: 'list_containers',
description: 'List Docker containers with filtering and status information. View running containers, check container status.',
inputSchema: {
type: 'object',
properties: {
all: {
type: 'boolean',
description: 'Include stopped containers'
},
filter: {
type: 'object',
description: 'Filter criteria'
},
format: {
type: 'string',
description: 'Output format'
}
}
}
},
{
name: 'execute_in_container',
description: 'Execute commands inside running Docker containers. Debug containers, run maintenance tasks.',
inputSchema: {
type: 'object',
properties: {
container: {
type: 'string',
description: 'Container name or ID'
},
command: {
type: 'string',
description: 'Command to execute'
},
interactive: {
type: 'boolean',
description: 'Interactive mode'
},
tty: {
type: 'boolean',
description: 'Allocate pseudo-TTY'
},
user: {
type: 'string',
description: 'User to run command as'
}
},
required: ['container', 'command']
}
}
];
// Create and run the server
const server = new MockMCPServer(serverInfo, tools);
server.run().catch(console.error);
```
--------------------------------------------------------------------------------
/RELEASE.md:
--------------------------------------------------------------------------------
```markdown
# Release Process
This document describes how to release a new version of NCP.
## Automated Release via GitHub Actions
### Prerequisites
1. All changes committed and pushed to `main`
2. All tests passing
3. Clean working directory
### Release Steps
1. **Trigger Release Workflow**
- Go to Actions → Release workflow
- Click "Run workflow"
- Select release type: `patch`, `minor`, or `major`
- Optionally check "Dry run" to test without publishing
2. **What Happens Automatically**
The release workflow (`release.yml`) will:
- ✅ Run full test suite
- ✅ Build the project
- ✅ Bump version in `package.json`
- ✅ Update `CHANGELOG.md` with conventional commits
- ✅ Create git tag (e.g., `1.4.0`)
- ✅ Push tag to GitHub
- ✅ Create GitHub Release
- ✅ Publish to NPM (`@portel/ncp`)
3. **MCP Registry Publication** (Automatic)
After GitHub Release is published, the MCP registry workflow (`publish-mcp-registry.yml`) automatically:
- ✅ Syncs version to `server.json`
- ✅ Validates `server.json` against MCP schema
- ✅ Downloads MCP Publisher CLI
- ✅ Authenticates via GitHub OIDC (no secrets needed!)
- ✅ Publishes to MCP Registry
**Registry Details**:
- Package: `io.github.portel-dev/ncp`
- Authentication: GitHub OIDC (automatic via `id-token: write` permission)
- No manual steps required!
## Manual Release (Not Recommended)
If you need to release manually:
```bash
# Ensure clean state
git status
# Run release-it
npm run release
# This will:
# - Prompt for version bump type
# - Run tests
# - Update version and CHANGELOG
# - Create git tag
# - Push to GitHub
# - Publish to NPM
# MCP Registry will auto-publish when GitHub Release is created
```
## Version Numbering
We follow [Semantic Versioning](https://semver.org/):
- **Major** (X.0.0): Breaking changes
- **Minor** (x.X.0): New features (backward compatible)
- **Patch** (x.x.X): Bug fixes (backward compatible)
## Post-Release Checklist
After release completes:
- [ ] Verify NPM package: https://www.npmjs.com/package/@portel/ncp
- [ ] Check GitHub Release: https://github.com/portel-dev/ncp/releases
- [ ] Verify MCP Registry listing (may take a few minutes)
- [ ] Test installation: `npx @portel/ncp@latest --version`
- [ ] Announce release (if significant)
## Troubleshooting
### NPM Publish Failed
- Check NPM authentication in GitHub Secrets
- Verify package name isn't taken
- Check `.npmignore` for correct file exclusions
### MCP Registry Publish Failed
**Issue: Organization not detected with OIDC**
If you see "portel-dev organization not detected" with GitHub OIDC:
1. **Use GitHub Personal Access Token (Recommended)**:
- Create a GitHub PAT with `repo` and `read:org` scopes
- Go to: Settings → Developer settings → Personal access tokens → Tokens (classic)
- Generate new token with scopes: `repo`, `read:org`
- Add as GitHub Secret: `Settings → Secrets → Actions → New repository secret`
- Name: `MCP_GITHUB_TOKEN`
- Value: Your PAT
- Workflow will automatically fallback to PAT if OIDC fails
2. **Other troubleshooting**:
- Check GitHub Actions logs for `publish-mcp-registry` workflow
- Verify `server.json` is valid (run `jsonschema -i server.json /tmp/mcp-server.schema.json`)
- Ensure `id-token: write` permission is set in workflow
- Confirm you're an admin of `portel-dev` organization: `gh api orgs/portel-dev/memberships/$(gh api user -q .login)`
### Release Workflow Failed
- Check test failures in Actions logs
- Ensure clean working directory
- Verify all dependencies are installed
## Emergency Hotfix Process
For critical bugs requiring immediate release:
1. Create hotfix branch from affected release tag
2. Fix the bug
3. Follow normal release process with `patch` bump
4. Both NPM and MCP Registry will auto-publish
## Release Artifacts
Each release produces:
- **NPM Package**: `@portel/[email protected]` on npmjs.com
- **MCP Registry Entry**: `io.github.portel-dev/ncp` in MCP registry
- **GitHub Release**: Tagged release with changelog
- **Git Tag**: `X.Y.Z` (or `vX.Y.Z` format)
## Contact
For release issues or questions:
- GitHub Issues: https://github.com/portel-dev/ncp/issues
- Repository: https://github.com/portel-dev/ncp
```
--------------------------------------------------------------------------------
/docs/download-stats.md:
--------------------------------------------------------------------------------
```markdown
# NCP Download Statistics
**Last Updated:** Auto-updated by GitHub badges
## Total Downloads Across All Channels
| Distribution Method | Total Downloads | Latest Version |
|---------------------|-----------------|----------------|
| **npm Package** |  |  |
| **.mcpb Bundle** |  |  |
---
## Distribution Breakdown
### npm Package
- **Best for:** All MCP clients (Cursor, Cline, Continue, VS Code)
- **Includes:** Full CLI tools + MCP server
- **Auto-updates:** Via `npm update -g @portel/ncp`
- **Package size:** ~2.5MB
[](https://www.npmjs.com/package/@portel/ncp)
[](https://www.npmjs.com/package/@portel/ncp)
### .mcpb Bundle
- **Best for:** Claude Desktop users
- **Includes:** Slim MCP-only server (no CLI)
- **Auto-updates:** Through Claude Desktop
- **Bundle size:** 126KB (13% smaller)
[](https://github.com/portel-dev/ncp/releases/latest)
[](https://github.com/portel-dev/ncp/releases)
---
## Growth Metrics
### Monthly npm Downloads
### GitHub Release Downloads
---
## Version Adoption
| Version | Release Date | Downloads | Status |
|---------|--------------|-----------|--------|
| Latest |  |  | ✅ Active |
---
## How to Check Live Stats
### Via npm
```bash
npm info @portel/ncp
# Or use npm-stat for detailed analytics
npx npm-stat @portel/ncp
```
### Via GitHub API
```bash
# Run our custom script
node scripts/check-mcpb-downloads.js
```
### Via Shields.io API
```bash
# npm downloads (all time)
curl https://img.shields.io/npm/dt/@portel/ncp.json
# GitHub release downloads (all time)
curl https://img.shields.io/github/downloads/portel-dev/ncp/total.json
```
---
## Platform Breakdown
*Note: Platform-specific download statistics require implementing telemetry (see `docs/guides/telemetry-design.md`)*
Without telemetry, we can only track:
- ✅ Total downloads (npm + GitHub)
- ✅ Downloads per version
- ❌ Platform distribution (macOS/Windows/Linux)
- ❌ Active installations
- ❌ MCP client distribution
---
## Credibility Indicators
Use these badges in your documentation, website, or presentations:
### Compact Badges (for README)
```markdown
[](https://npmjs.com/package/@portel/ncp)
[](https://github.com/portel-dev/ncp/releases)
```
### Large Badges (for landing pages)
```markdown
[](https://npmjs.com/package/@portel/ncp)
[](https://github.com/portel-dev/ncp/releases)
```
---
## Share Your Success
Once you hit download milestones, celebrate with the community:
- 🎉 **1,000 downloads** - "NCP has reached 1K downloads! Thank you!"
- 🚀 **10,000 downloads** - "10K downloads milestone! Here's what's next..."
- 🌟 **100,000 downloads** - "100K downloads! Here's the impact..."
Share on:
- Twitter/X with `#ModelContextProtocol` `#MCP`
- LinkedIn tech community
- Hacker News (Show HN)
- Reddit (r/ChatGPT, r/ClaudeAI, r/LocalLLaMA)
```
--------------------------------------------------------------------------------
/src/cache/schema-cache.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Schema Cache
*
* Caches MCP configuration schemas for reuse across add/repair/import commands
* Stores in JSON files alongside CSV cache
*/
import fs from 'fs';
import path from 'path';
import { ConfigurationSchema } from '../services/config-schema-reader.js';
import { logger } from '../utils/logger.js';
export class SchemaCache {
private cacheDir: string;
constructor(cacheDir: string) {
this.cacheDir = path.join(cacheDir, 'schemas');
this.ensureCacheDir();
}
/**
* Ensure cache directory exists
*/
private ensureCacheDir(): void {
if (!fs.existsSync(this.cacheDir)) {
fs.mkdirSync(this.cacheDir, { recursive: true });
}
}
/**
* Save configuration schema to cache
*/
save(mcpName: string, schema: ConfigurationSchema): void {
try {
const filepath = this.getSchemaPath(mcpName);
const data = {
mcpName,
schema,
cachedAt: new Date().toISOString(),
version: '1.0'
};
fs.writeFileSync(filepath, JSON.stringify(data, null, 2), 'utf-8');
logger.debug(`Cached configuration schema for ${mcpName}`);
} catch (error: any) {
logger.error(`Failed to cache schema for ${mcpName}:`, error.message);
}
}
/**
* Load configuration schema from cache
*/
get(mcpName: string): ConfigurationSchema | null {
try {
const filepath = this.getSchemaPath(mcpName);
if (!fs.existsSync(filepath)) {
return null;
}
const data = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
logger.debug(`Loaded cached schema for ${mcpName}`);
return data.schema as ConfigurationSchema;
} catch (error: any) {
logger.error(`Failed to load cached schema for ${mcpName}:`, error.message);
return null;
}
}
/**
* Check if schema is cached
*/
has(mcpName: string): boolean {
const filepath = this.getSchemaPath(mcpName);
return fs.existsSync(filepath);
}
/**
* Delete cached schema
*/
delete(mcpName: string): void {
try {
const filepath = this.getSchemaPath(mcpName);
if (fs.existsSync(filepath)) {
fs.unlinkSync(filepath);
logger.debug(`Deleted cached schema for ${mcpName}`);
}
} catch (error: any) {
logger.error(`Failed to delete cached schema for ${mcpName}:`, error.message);
}
}
/**
* Clear all cached schemas
*/
clear(): void {
try {
if (fs.existsSync(this.cacheDir)) {
const files = fs.readdirSync(this.cacheDir);
for (const file of files) {
if (file.endsWith('.schema.json')) {
fs.unlinkSync(path.join(this.cacheDir, file));
}
}
logger.debug('Cleared all cached schemas');
}
} catch (error: any) {
logger.error('Failed to clear schema cache:', error.message);
}
}
/**
* Get all cached schemas
*/
listAll(): Array<{ mcpName: string; cachedAt: string }> {
try {
if (!fs.existsSync(this.cacheDir)) {
return [];
}
const files = fs.readdirSync(this.cacheDir);
const schemas: Array<{ mcpName: string; cachedAt: string }> = [];
for (const file of files) {
if (file.endsWith('.schema.json')) {
const filepath = path.join(this.cacheDir, file);
const data = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
schemas.push({
mcpName: data.mcpName,
cachedAt: data.cachedAt
});
}
}
return schemas;
} catch (error: any) {
logger.error('Failed to list cached schemas:', error.message);
return [];
}
}
/**
* Get file path for schema
*/
private getSchemaPath(mcpName: string): string {
// Sanitize MCP name for filename
const safeName = mcpName.replace(/[^a-zA-Z0-9-_]/g, '_');
return path.join(this.cacheDir, `${safeName}.schema.json`);
}
/**
* Get cache statistics
*/
getStats(): { total: number; oldestCache: string | null; newestCache: string | null } {
const all = this.listAll();
if (all.length === 0) {
return { total: 0, oldestCache: null, newestCache: null };
}
const sorted = all.sort((a, b) =>
new Date(a.cachedAt).getTime() - new Date(b.cachedAt).getTime()
);
return {
total: all.length,
oldestCache: sorted[0].cachedAt,
newestCache: sorted[sorted.length - 1].cachedAt
};
}
}
```
--------------------------------------------------------------------------------
/src/utils/schema-examples.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Dynamic Schema Examples Generator
*
* Generates realistic examples from actual available tools instead of hardcoded dummy examples
*/
export class SchemaExamplesGenerator {
private tools: Array<{name: string, description: string}> = [];
constructor(availableTools: Array<{name: string, description: string}>) {
this.tools = availableTools;
}
/**
* Get realistic tool execution examples
*/
getToolExecutionExamples(): string[] {
const examples: string[] = [];
// Always include Shell if available (most common)
const shellTool = this.tools.find(t => t.name.startsWith('Shell:'));
if (shellTool) {
examples.push(shellTool.name);
}
// Add file operation example
const fileTools = this.tools.filter(t =>
t.description?.toLowerCase().includes('file') ||
t.name.includes('write') ||
t.name.includes('read')
);
if (fileTools.length > 0) {
examples.push(fileTools[0].name);
}
// Add one more diverse example
const otherTool = this.tools.find(t =>
!t.name.startsWith('Shell:') &&
!examples.includes(t.name)
);
if (otherTool) {
examples.push(otherTool.name);
}
return examples.slice(0, 3); // Max 3 examples
}
/**
* Get realistic discovery query examples
*/
getDiscoveryExamples(): string[] {
const examples: string[] = [];
// Analyze available tools to suggest realistic queries
const hasFileOps = this.tools.some(t => t.description?.toLowerCase().includes('file'));
const hasGit = this.tools.some(t => t.description?.toLowerCase().includes('git'));
const hasWeb = this.tools.some(t => t.description?.toLowerCase().includes('web') || t.description?.toLowerCase().includes('search'));
if (hasFileOps) examples.push('create a new file');
if (hasGit) examples.push('check git status');
if (hasWeb) examples.push('search the web');
// Generic fallbacks
if (examples.length === 0) {
examples.push('run a command', 'list files');
}
return examples.slice(0, 3);
}
/**
* Generate complete tool execution schema with dynamic examples
*/
getToolExecutionSchema() {
const examples = this.getToolExecutionExamples();
const exampleText = examples.length > 0
? `(e.g., ${examples.map(e => `"${e}"`).join(', ')})`
: '(use the discover_tools command to find available tools)';
return {
type: 'string',
description: `The specific tool name to execute ${exampleText}`
};
}
/**
* Generate discovery schema with realistic examples
*/
getDiscoverySchema() {
const examples = this.getDiscoveryExamples();
const exampleText = examples.length > 0
? `(e.g., ${examples.map(e => `"${e}"`).join(', ')})`
: '';
return {
type: 'string',
description: `Natural language description of what you want to do ${exampleText}`
};
}
/**
* Get tool categories for better organization
*/
getToolCategories(): {[category: string]: string[]} {
const categories: {[category: string]: string[]} = {};
for (const tool of this.tools) {
const desc = tool.description?.toLowerCase() || '';
const name = tool.name.toLowerCase();
if (name.includes('shell') || desc.includes('command')) {
categories['System Commands'] = categories['System Commands'] || [];
categories['System Commands'].push(tool.name);
} else if (desc.includes('file') || name.includes('read') || name.includes('write')) {
categories['File Operations'] = categories['File Operations'] || [];
categories['File Operations'].push(tool.name);
} else if (desc.includes('web') || desc.includes('search')) {
categories['Web & Search'] = categories['Web & Search'] || [];
categories['Web & Search'].push(tool.name);
} else if (desc.includes('git')) {
categories['Git Operations'] = categories['Git Operations'] || [];
categories['Git Operations'].push(tool.name);
} else {
categories['Other Tools'] = categories['Other Tools'] || [];
categories['Other Tools'].push(tool.name);
}
}
return categories;
}
}
/**
* Fallback examples when no tools are available yet (startup scenario)
*/
export const FALLBACK_EXAMPLES = {
toolExecution: [
'"Shell:run_command"',
'"desktop-commander:write_file"'
],
discovery: [
'"run a shell command"',
'"create a new file"',
'"search for something"'
]
};
```
--------------------------------------------------------------------------------
/test/mock-mcps/aws-server.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Mock AWS MCP Server
* Real MCP server structure for AWS services testing
*/
import { MockMCPServer } from './base-mock-server.js';
const serverInfo = {
name: 'aws-test',
version: '1.0.0',
description: 'Amazon Web Services integration for EC2, S3, Lambda, and cloud resource management'
};
const tools = [
{
name: 'create_ec2_instance',
description: 'Launch new EC2 virtual machine instances with configuration. Create servers, deploy applications to cloud.',
inputSchema: {
type: 'object',
properties: {
image_id: {
type: 'string',
description: 'AMI ID for instance'
},
instance_type: {
type: 'string',
description: 'Instance size (t2.micro, m5.large, etc.)'
},
key_name: {
type: 'string',
description: 'Key pair name for SSH access'
},
security_groups: {
type: 'array',
description: 'Security group names',
items: { type: 'string' }
},
tags: {
type: 'object',
description: 'Instance tags as key-value pairs'
}
},
required: ['image_id', 'instance_type']
}
},
{
name: 'upload_to_s3',
description: 'Upload files and objects to S3 storage buckets. Store files in cloud, backup data, host static content.',
inputSchema: {
type: 'object',
properties: {
bucket: {
type: 'string',
description: 'S3 bucket name'
},
key: {
type: 'string',
description: 'Object key/path in bucket'
},
file_path: {
type: 'string',
description: 'Local file path to upload'
},
content_type: {
type: 'string',
description: 'MIME type of file'
},
public: {
type: 'boolean',
description: 'Make object publicly accessible'
}
},
required: ['bucket', 'key', 'file_path']
}
},
{
name: 'create_lambda_function',
description: 'Deploy serverless Lambda functions for event-driven computing. Run code without servers, process events.',
inputSchema: {
type: 'object',
properties: {
function_name: {
type: 'string',
description: 'Lambda function name'
},
runtime: {
type: 'string',
description: 'Runtime environment (nodejs18.x, python3.9, etc.)'
},
handler: {
type: 'string',
description: 'Function handler entry point'
},
code: {
type: 'object',
description: 'Function code (zip file or inline)'
},
role: {
type: 'string',
description: 'IAM role ARN for execution'
}
},
required: ['function_name', 'runtime', 'handler', 'code', 'role']
}
},
{
name: 'list_resources',
description: 'List AWS resources across services with filtering options. View EC2 instances, S3 buckets, Lambda functions.',
inputSchema: {
type: 'object',
properties: {
service: {
type: 'string',
description: 'AWS service name (ec2, s3, lambda, etc.)'
},
region: {
type: 'string',
description: 'AWS region to query'
},
filters: {
type: 'object',
description: 'Service-specific filters'
}
},
required: ['service']
}
},
{
name: 'create_rds_database',
description: 'Create managed RDS database instances with configuration. Set up MySQL, PostgreSQL databases in cloud.',
inputSchema: {
type: 'object',
properties: {
db_name: {
type: 'string',
description: 'Database instance identifier'
},
engine: {
type: 'string',
description: 'Database engine (mysql, postgres, etc.)'
},
instance_class: {
type: 'string',
description: 'Database instance size'
},
allocated_storage: {
type: 'number',
description: 'Storage size in GB'
},
username: {
type: 'string',
description: 'Master username'
},
password: {
type: 'string',
description: 'Master password'
}
},
required: ['db_name', 'engine', 'instance_class', 'allocated_storage', 'username', 'password']
}
}
];
// Create and run the server
const server = new MockMCPServer(serverInfo, tools);
server.run().catch(console.error);
```
--------------------------------------------------------------------------------
/docs/mcp-registry-setup.md:
--------------------------------------------------------------------------------
```markdown
# MCP Registry Publishing Setup
## Overview
NCP automatically publishes to the MCP Registry when a GitHub Release is created. This document explains the authentication setup.
## Authentication Methods
### Method 1: GitHub OIDC (Automatic)
**Pros**:
- ✅ No secrets to configure
- ✅ Automatic via GitHub Actions
- ✅ Most secure (short-lived tokens)
**Cons**:
- ⚠️ May not detect organization membership correctly
- ⚠️ Known issue with `portel-dev` organization detection
**How it works**:
- Workflow has `id-token: write` permission
- GitHub Actions generates OIDC token automatically
- MCP Publisher uses token to authenticate
**No setup required** - works out of the box (if organization detection works)
---
### Method 2: GitHub Personal Access Token (Fallback)
**Use this if OIDC fails to detect `portel-dev` organization**
#### Setup Steps
1. **Create GitHub PAT**:
- Go to: https://github.com/settings/tokens
- Click: "Tokens (classic)" → "Generate new token (classic)"
- Name: `MCP Registry Publishing`
- Scopes needed:
- ✅ `repo` (Full control of private repositories)
- ✅ `read:org` (Read org and team membership)
- Click "Generate token"
- **Copy the token** (you won't see it again!)
2. **Add as GitHub Secret**:
- Go to: https://github.com/portel-dev/ncp/settings/secrets/actions
- Click: "New repository secret"
- Name: `MCP_GITHUB_TOKEN`
- Value: Paste your PAT
- Click: "Add secret"
3. **Workflow will automatically use it**:
- Workflow tries OIDC first
- If OIDC fails, falls back to `MCP_GITHUB_TOKEN`
- No code changes needed!
---
## Verification
### Check Organization Membership
Verify you're an admin of `portel-dev`:
```bash
gh api orgs/portel-dev/memberships/$(gh api user -q .login)
```
Expected output:
```json
{
"role": "admin",
"state": "active"
}
```
### Check Repository Permissions
```bash
gh api repos/portel-dev/ncp/collaborators/$(gh api user -q .login)/permission
```
Expected output:
```json
{
"permission": "admin",
"role_name": "admin"
}
```
### Validate server.json
```bash
curl -sS https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json -o /tmp/server.schema.json
jsonschema -i server.json /tmp/server.schema.json
```
Should output: (no errors = valid)
---
## Testing the Workflow
### Option 1: Wait for Real Release
The workflow triggers automatically when you publish a GitHub Release via the Release workflow.
### Option 2: Manual Test (Local)
You can test MCP Publisher authentication locally:
```bash
# Download MCP Publisher
VERSION="v1.1.0"
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/${VERSION}/mcp-publisher_${VERSION#v}_${OS}_${ARCH}.tar.gz" | tar xz
# Test authentication
./mcp-publisher login github-oidc # Try OIDC first
# Or with PAT
export GITHUB_TOKEN="your-pat-here"
echo "$GITHUB_TOKEN" | ./mcp-publisher login github --token-stdin
# Dry run publish (doesn't actually publish)
./mcp-publisher publish --dry-run
```
---
## Troubleshooting
### "Organization portel-dev not detected"
**Solution**: Use GitHub PAT (Method 2 above)
This is a known limitation with GitHub OIDC tokens not always exposing organization membership.
### "Authentication failed"
**Check**:
1. PAT is valid and not expired
2. PAT has `repo` and `read:org` scopes
3. Secret name is exactly `MCP_GITHUB_TOKEN`
4. You're an admin of `portel-dev` organization
### "Invalid server.json"
**Check**:
- Description is ≤100 characters
- Version format is valid (e.g., `1.4.0`)
- All required fields present
- Run validation: `jsonschema -i server.json /tmp/server.schema.json`
---
## Security Notes
### GitHub PAT Best Practices
- ✅ Use classic tokens (fine-grained tokens not yet supported by MCP Publisher)
- ✅ Minimum scopes: `repo`, `read:org`
- ✅ Store as GitHub Secret (never commit to code)
- ✅ Rotate token periodically
- ✅ Revoke immediately if compromised
### OIDC vs PAT
| Feature | OIDC | PAT |
|---------|------|-----|
| Security | ⭐⭐⭐⭐⭐ Short-lived | ⭐⭐⭐ Long-lived |
| Setup | Zero config | Requires secret |
| Org Detection | ⚠️ May fail | ✅ Reliable |
| Recommended | If it works | If OIDC fails |
---
## What Gets Published
Each release publishes to:
1. **NPM**: `@portel/[email protected]`
2. **MCP Registry**: `io.github.portel-dev/ncp`
3. **GitHub Releases**: Tagged release
All automatic via GitHub Actions!
---
## Support
If you encounter issues:
1. Check GitHub Actions logs
2. Review this troubleshooting guide
3. Test authentication locally
4. Open an issue: https://github.com/portel-dev/ncp/issues
```
--------------------------------------------------------------------------------
/src/utils/parameter-prompter.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Interactive parameter prompting system
* Guides users through tool parameters with intelligent prompts
*/
import * as readline from 'readline';
import chalk from 'chalk';
export interface ParameterInfo {
name: string;
type: string;
required: boolean;
description?: string;
}
export class ParameterPrompter {
private rl: readline.Interface;
constructor() {
this.rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
}
/**
* Prompt user for all tool parameters interactively
*/
async promptForParameters(
toolName: string,
parameters: ParameterInfo[],
predictor: any,
toolContext: string
): Promise<any> {
console.log(chalk.blue(`📝 Tool "${toolName}" requires parameters. Let me guide you through them:\n`));
const result: any = {};
// Sort parameters: required first, then optional
const sortedParams = [...parameters].sort((a, b) => {
if (a.required && !b.required) return -1;
if (!a.required && b.required) return 1;
return 0;
});
for (const param of sortedParams) {
const value = await this.promptForParameter(param, predictor, toolContext, toolName);
if (value !== null && value !== undefined && value !== '') {
result[param.name] = this.convertValue(value, param.type);
}
}
return result;
}
/**
* Prompt for a single parameter
*/
private async promptForParameter(
param: ParameterInfo,
predictor: any,
toolContext: string,
toolName: string
): Promise<string | null> {
const icon = param.required ? '📄' : '📔';
const status = param.required ? 'Required' : 'Optional';
const typeInfo = chalk.cyan(`(${param.type})`);
console.log(`${icon} ${chalk.bold(param.name)} ${typeInfo} - ${chalk.yellow(status)}`);
if (param.description) {
console.log(` ${chalk.gray(param.description)}`);
}
// Generate intelligent suggestion
const suggestion = predictor.predictValue(
param.name,
param.type,
toolContext,
param.description,
toolName
);
let prompt = ' Enter value';
if (!param.required) {
prompt += ' (press Enter to skip)';
}
if (suggestion && typeof suggestion === 'string' && suggestion !== 'example') {
prompt += ` [${chalk.green(suggestion)}]`;
}
prompt += ': ';
const input = await this.question(prompt);
// If user pressed Enter and we have a suggestion, use it
if (input === '' && suggestion && param.required) {
console.log(` ${chalk.gray(`Using suggested value: ${suggestion}`)}`);
return String(suggestion);
}
// If optional and empty, skip
if (input === '' && !param.required) {
console.log(` ${chalk.gray('Skipped')}`);
return null;
}
// If required but empty, use suggestion or ask again
if (input === '' && param.required) {
if (suggestion) {
console.log(` ${chalk.gray(`Using suggested value: ${suggestion}`)}`);
return String(suggestion);
} else {
console.log(chalk.red(' This parameter is required. Please provide a value.'));
return await this.promptForParameter(param, predictor, toolContext, toolName);
}
}
console.log(); // Add spacing
return input;
}
/**
* Convert string input to appropriate type
*/
private convertValue(value: string, type: string): any {
if (value === '') return undefined;
switch (type) {
case 'number':
case 'integer':
const num = Number(value);
return isNaN(num) ? value : num;
case 'boolean':
const lower = value.toLowerCase();
if (lower === 'true' || lower === 'yes' || lower === '1') return true;
if (lower === 'false' || lower === 'no' || lower === '0') return false;
return Boolean(value);
case 'array':
try {
// Try to parse as JSON array first
if (value.startsWith('[')) {
return JSON.parse(value);
}
// Otherwise split by comma
return value.split(',').map(s => s.trim());
} catch {
return value.split(',').map(s => s.trim());
}
case 'object':
try {
return JSON.parse(value);
} catch {
return { value };
}
default:
return value;
}
}
/**
* Prompt user with a question
*/
private question(prompt: string): Promise<string> {
return new Promise((resolve) => {
this.rl.question(prompt, (answer) => {
resolve(answer.trim());
});
});
}
/**
* Close the readline interface
*/
close(): void {
this.rl.close();
}
}
```
--------------------------------------------------------------------------------
/src/utils/paths.ts:
--------------------------------------------------------------------------------
```typescript
/**
* NCP Standardized File System Paths
*
* This file defines all file paths used by NCP components.
* DO NOT hardcode paths elsewhere - always import from here.
*
* Cross-platform directory locations:
* - Windows: %APPDATA%\ncp\ (e.g., C:\Users\Username\AppData\Roaming\ncp\)
* - macOS: ~/Library/Preferences/ncp/
* - Linux: ~/.config/ncp/
*
* See NCP_FILE_SYSTEM_ARCHITECTURE.md for complete documentation.
*/
import * as path from 'path';
import * as os from 'os';
import * as fs from 'fs/promises';
import envPaths from 'env-paths';
// Cross-platform user directories using env-paths
const paths = envPaths('ncp');
// Base Directories (cross-platform)
export const NCP_BASE_DIR = paths.config;
export const NCP_PROFILES_DIR = path.join(NCP_BASE_DIR, 'profiles');
export const NCP_CACHE_DIR = path.join(NCP_BASE_DIR, 'cache');
export const NCP_LOGS_DIR = path.join(NCP_BASE_DIR, 'logs');
export const NCP_CONFIG_DIR = path.join(NCP_BASE_DIR, 'config');
export const NCP_TEMP_DIR = path.join(NCP_BASE_DIR, 'temp');
// Profile Files
export const PROFILE_ALL = path.join(NCP_PROFILES_DIR, 'all.json');
export const PROFILE_CLAUDE_DESKTOP = path.join(NCP_PROFILES_DIR, 'claude-desktop.json');
export const PROFILE_CLAUDE_CODE = path.join(NCP_PROFILES_DIR, 'claude-code.json');
export const PROFILE_DEV = path.join(NCP_PROFILES_DIR, 'dev.json');
export const PROFILE_MINIMAL = path.join(NCP_PROFILES_DIR, 'minimal.json');
// Cache Files (currently stored in base directory, not cache subdirectory)
export const TOOL_CACHE_FILE = path.join(NCP_BASE_DIR, 'tool-cache.json');
export const MCP_HEALTH_CACHE = path.join(NCP_BASE_DIR, 'mcp-health.json');
export const DISCOVERY_INDEX_CACHE = path.join(NCP_CACHE_DIR, 'discovery-index.json');
// Profile-specific vector database files
export const EMBEDDINGS_DIR = path.join(NCP_CACHE_DIR, 'embeddings');
export const EMBEDDINGS_METADATA_DIR = path.join(NCP_CACHE_DIR, 'metadata');
// Log Files
export const MAIN_LOG_FILE = path.join(NCP_LOGS_DIR, 'ncp.log');
export const MCP_LOG_FILE = path.join(NCP_LOGS_DIR, 'mcp-connections.log');
export const DISCOVERY_LOG_FILE = path.join(NCP_LOGS_DIR, 'discovery.log');
// Config Files
export const GLOBAL_SETTINGS = path.join(NCP_CONFIG_DIR, 'settings.json');
// Client-specific configs
export const CLIENT_CONFIGS_DIR = path.join(NCP_CONFIG_DIR, 'client-configs');
export const CLAUDE_DESKTOP_CONFIG = path.join(CLIENT_CONFIGS_DIR, 'claude-desktop.json');
export const CLAUDE_CODE_CONFIG = path.join(CLIENT_CONFIGS_DIR, 'claude-code.json');
// Temporary directories
export const MCP_PROBES_TEMP = path.join(NCP_TEMP_DIR, 'mcp-probes');
export const INSTALLATION_TEMP = path.join(NCP_TEMP_DIR, 'installation');
/**
* Ensures all NCP directories exist
* MUST be called on startup by all NCP components
*/
export async function ensureNCPDirectories(): Promise<void> {
const directories = [
NCP_BASE_DIR,
NCP_PROFILES_DIR,
NCP_CACHE_DIR,
NCP_LOGS_DIR,
NCP_CONFIG_DIR,
NCP_TEMP_DIR,
CLIENT_CONFIGS_DIR,
MCP_PROBES_TEMP,
INSTALLATION_TEMP,
EMBEDDINGS_DIR,
EMBEDDINGS_METADATA_DIR
];
for (const dir of directories) {
try {
await fs.mkdir(dir, { recursive: true });
} catch (error) {
console.error(`Failed to create directory ${dir}:`, error);
}
}
}
/**
* Gets profile path by name
* @param profileName - Name of the profile (without .json extension)
* @returns Full path to profile file
*/
export function getProfilePath(profileName: string): string {
return path.join(NCP_PROFILES_DIR, `${profileName}.json`);
}
/**
* Migration utility: Move file if it exists at old location
* @param oldPath - Current file location
* @param newPath - New standardized location
*/
export async function migrateFile(oldPath: string, newPath: string): Promise<boolean> {
try {
// Check if old file exists
await fs.access(oldPath);
// Ensure new directory exists
await fs.mkdir(path.dirname(newPath), { recursive: true });
// Move file
await fs.rename(oldPath, newPath);
console.log(`Migrated: ${oldPath} → ${newPath}`);
return true;
} catch (error) {
// File doesn't exist at old location, that's fine
return false;
}
}
/**
* Migrate all files from old locations to standardized locations
* Should be called once during upgrade
*/
export async function migrateAllFiles(): Promise<void> {
console.log('Starting NCP file migration...');
// Migrate tool cache
await migrateFile('.tool-cache.json', TOOL_CACHE_FILE);
await migrateFile('tool-cache.json', TOOL_CACHE_FILE);
// Migrate old profile files
await migrateFile('.ncp/profiles/default.json', PROFILE_ALL);
await migrateFile('.ncp/profiles/development.json', PROFILE_DEV);
console.log('NCP file migration complete');
}
```
--------------------------------------------------------------------------------
/test/mock-mcps/filesystem-server.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Mock Filesystem MCP Server
* Real MCP server structure for file system operations testing
*/
import { MockMCPServer } from './base-mock-server.js';
const serverInfo = {
name: 'filesystem-test',
version: '1.0.0',
description: 'Local file system operations including reading, writing, directory management, and permissions'
};
const tools = [
{
name: 'read_file',
description: 'Read contents of files from local filesystem. Load configuration files, read text documents, access data files.',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'File path to read'
},
encoding: {
type: 'string',
description: 'Text encoding (utf8, ascii, etc.)'
}
},
required: ['path']
}
},
{
name: 'write_file',
description: 'Write content to files on local filesystem. Create configuration files, save data, generate reports.',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'File path to write to'
},
content: {
type: 'string',
description: 'Content to write to file'
},
encoding: {
type: 'string',
description: 'Text encoding (utf8, ascii, etc.)'
},
create_dirs: {
type: 'boolean',
description: 'Create parent directories if they do not exist'
}
},
required: ['path', 'content']
}
},
{
name: 'create_directory',
description: 'Create new directories and folder structures. Organize files, set up project structure, create folder hierarchies.',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'Directory path to create'
},
recursive: {
type: 'boolean',
description: 'Create parent directories if needed'
},
mode: {
type: 'string',
description: 'Directory permissions (octal notation)'
}
},
required: ['path']
}
},
{
name: 'list_directory',
description: 'List files and directories with filtering and sorting options. Browse folders, find files, explore directory structure.',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'Directory path to list'
},
recursive: {
type: 'boolean',
description: 'Include subdirectories recursively'
},
include_hidden: {
type: 'boolean',
description: 'Include hidden files and directories'
},
pattern: {
type: 'string',
description: 'Glob pattern to filter files'
}
},
required: ['path']
}
},
{
name: 'delete_file',
description: 'Delete files and directories from filesystem. Remove old files, clean up temporary data, delete folders.',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'File or directory path to delete'
},
recursive: {
type: 'boolean',
description: 'Delete directories and contents recursively'
},
force: {
type: 'boolean',
description: 'Force deletion without confirmation'
}
},
required: ['path']
}
},
{
name: 'copy_file',
description: 'Copy files and directories to new locations. Backup files, duplicate data, organize content.',
inputSchema: {
type: 'object',
properties: {
source: {
type: 'string',
description: 'Source file or directory path'
},
destination: {
type: 'string',
description: 'Destination path for copy'
},
overwrite: {
type: 'boolean',
description: 'Overwrite destination if it exists'
},
preserve_attributes: {
type: 'boolean',
description: 'Preserve file timestamps and permissions'
}
},
required: ['source', 'destination']
}
},
{
name: 'get_file_info',
description: 'Get detailed information about files and directories. Check file size, modification time, permissions.',
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'File or directory path'
},
follow_symlinks: {
type: 'boolean',
description: 'Follow symbolic links'
}
},
required: ['path']
}
}
];
// Create and run the server
const server = new MockMCPServer(serverInfo, tools);
server.run().catch(console.error);
```
--------------------------------------------------------------------------------
/test/final-coverage-push.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Final Coverage Push - Simple targeted tests to reach 80% coverage
* Focus on easy wins and edge cases
*/
import { describe, it, expect } from '@jest/globals';
import { DiscoveryEngine } from '../src/discovery/engine.js';
import { PersistentRAGEngine } from '../src/discovery/rag-engine.js';
describe('Final Coverage Push - Simple Tests', () => {
describe('Discovery Engine Pattern Extraction', () => {
it('should extract patterns from complex tool descriptions', async () => {
const engine = new DiscoveryEngine();
// Test with tool that has complex description patterns
await engine.indexTool({
id: 'complex:multi-operation-tool',
name: 'multi-operation-tool',
description: 'Create, read, update and delete multiple files in directory while executing commands and validating operations'
});
// Should extract multiple verb-object patterns
const stats = engine.getStats();
expect(stats.totalPatterns).toBeGreaterThan(5);
});
it('should handle pattern extraction edge cases', async () => {
const engine = new DiscoveryEngine();
// Test with empty and problematic descriptions
const problematicTools = [
{
id: 'empty:desc',
name: 'empty-desc',
description: ''
},
{
id: 'special:chars',
name: 'special-chars',
description: 'Tool with "quoted text" and (parentheses) and symbols @#$%'
},
{
id: 'long:name-with-many-parts',
name: 'very-long-tool-name-with-many-hyphenated-parts',
description: 'Normal description'
}
];
for (const tool of problematicTools) {
await engine.indexTool(tool);
}
// Should handle all cases without errors
const stats = engine.getStats();
expect(stats.totalTools).toBe(3);
});
it('should test findRelatedTools similarity calculation', async () => {
const engine = new DiscoveryEngine();
// Index multiple related tools
const tools = [
{
id: 'fileops:read',
name: 'fileops:read',
description: 'Read file content from filesystem'
},
{
id: 'fileops:write',
name: 'fileops:write',
description: 'Write file content to filesystem'
},
{
id: 'mathops:calculate',
name: 'mathops:calculate',
description: 'Perform mathematical calculations'
}
];
for (const tool of tools) {
await engine.indexTool(tool);
}
// Find related tools for the read operation
const related = await engine.findRelatedTools('fileops:read');
expect(related.length).toBeGreaterThan(0);
// Should find write operation as related (similar description)
const writeRelated = related.find(r => r.id === 'fileops:write');
expect(writeRelated).toBeTruthy();
expect(writeRelated?.similarity).toBeGreaterThan(0.3);
});
});
describe('RAG Engine Basic Operations', () => {
it('should handle minimal tool indexing', async () => {
const ragEngine = new PersistentRAGEngine();
await ragEngine.initialize();
// Index tool with minimal description
await ragEngine.indexMCP('minimal-server', [
{
id: 'minimal:tool',
name: 'tool',
description: 'x', // Very short description
inputSchema: {}
}
]);
// Test discovery with empty/minimal query
const results = await ragEngine.discover('', 5);
expect(Array.isArray(results)).toBe(true);
});
it('should handle cache operations', async () => {
const ragEngine = new PersistentRAGEngine();
await ragEngine.initialize();
// Index some tools
await ragEngine.indexMCP('test-server', [
{
id: 'test:refresh-tool',
name: 'refresh-tool',
description: 'Tool for testing cache refresh operations',
inputSchema: {}
}
]);
// Test cache refresh
await ragEngine.refreshCache();
// Test cache clear
await ragEngine.clearCache();
// Should still work after clear
const results = await ragEngine.discover('refresh', 1);
expect(Array.isArray(results)).toBe(true);
});
it('should handle domain classification', async () => {
const ragEngine = new PersistentRAGEngine();
await ragEngine.initialize();
// Test with query that contains multiple domain indicators
await ragEngine.indexMCP('multi-domain', [
{
id: 'multi:payment-file-web',
name: 'payment-file-web',
description: 'Process payment files on web server database',
inputSchema: {}
}
]);
const results = await ragEngine.discover('payment web database file', 3);
expect(results.length).toBeGreaterThanOrEqual(0);
});
});
});
```
--------------------------------------------------------------------------------
/src/services/tool-finder.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Shared service for tool discovery and search
* Handles pagination, filtering, and result organization
*/
import { NCPOrchestrator } from '../orchestrator/ncp-orchestrator.js';
export interface FindOptions {
query?: string;
page?: number;
limit?: number;
depth?: number;
mcpFilter?: string | null;
}
export interface PaginationInfo {
page: number;
totalPages: number;
totalResults: number;
startIndex: number;
endIndex: number;
resultsInPage: number;
}
export interface GroupedTool {
toolName: string;
confidence: number;
description?: string;
schema?: any;
}
export interface FindResult {
tools: any[];
groupedByMCP: Record<string, GroupedTool[]>;
pagination: PaginationInfo;
mcpFilter: string | null;
isListing: boolean;
query: string;
}
export class ToolFinder {
constructor(private orchestrator: NCPOrchestrator) {}
/**
* Main search method with all features
*/
async find(options: FindOptions = {}): Promise<FindResult> {
const {
query = '',
page = 1,
limit = query ? 5 : 20,
depth = 2,
mcpFilter = null
} = options;
// Detect MCP-specific search if not explicitly provided
const detectedMCPFilter = mcpFilter || this.detectMCPFilter(query);
// Adjust search query based on MCP filter
const searchQuery = detectedMCPFilter ? '' : query;
// Get results with proper confidence-based ordering from orchestrator
// Request enough for pagination but not excessive amounts
const searchLimit = Math.min(1000, (page * limit) + 50); // Get enough for current page + buffer
const allResults = await this.orchestrator.find(searchQuery, searchLimit, depth >= 1);
// Apply MCP filtering if detected
const filteredResults = detectedMCPFilter ?
allResults.filter(r => r.mcpName.toLowerCase() === detectedMCPFilter.toLowerCase()) :
allResults;
// Results are already sorted by confidence from orchestrator - maintain that order
// Calculate pagination
const pagination = this.calculatePagination(filteredResults.length, page, limit);
// Get page results while preserving confidence-based order
const pageResults = filteredResults.slice(pagination.startIndex, pagination.endIndex);
// Group by MCP
const groupedByMCP = this.groupByMCP(pageResults);
return {
tools: pageResults,
groupedByMCP,
pagination,
mcpFilter: detectedMCPFilter,
isListing: !query || query.trim() === '',
query
};
}
/**
* Calculate pagination details
*/
private calculatePagination(totalResults: number, page: number, limit: number): PaginationInfo {
const totalPages = Math.ceil(totalResults / limit);
const safePage = Math.max(1, Math.min(page, totalPages || 1));
const startIndex = (safePage - 1) * limit;
const endIndex = Math.min(startIndex + limit, totalResults);
return {
page: safePage,
totalPages,
totalResults,
startIndex,
endIndex,
resultsInPage: endIndex - startIndex
};
}
/**
* Group tools by their MCP
*/
private groupByMCP(results: any[]): Record<string, GroupedTool[]> {
const groups: Record<string, GroupedTool[]> = {};
results.forEach(result => {
if (!groups[result.mcpName]) {
groups[result.mcpName] = [];
}
groups[result.mcpName].push({
toolName: result.toolName,
confidence: result.confidence,
description: result.description,
schema: result.schema
});
});
return groups;
}
/**
* Detect if query is an MCP-specific search
*/
private detectMCPFilter(query: string): string | null {
if (!query) return null;
const lowerQuery = query.toLowerCase().trim();
// Common MCP names to check
const knownMCPs = [
'filesystem', 'memory', 'shell', 'portel', 'tavily',
'desktop-commander', 'stripe', 'sequential-thinking',
'context7-mcp', 'github', 'gitlab', 'slack'
];
// Check for exact MCP name match
for (const mcp of knownMCPs) {
if (lowerQuery === mcp || lowerQuery === `${mcp}:`) {
return mcp;
}
}
// Check if query starts with MCP:tool pattern
if (lowerQuery.includes(':')) {
const [potentialMCP] = lowerQuery.split(':');
if (knownMCPs.includes(potentialMCP)) {
return potentialMCP;
}
}
return null;
}
/**
* Get sample tools when no results found
*/
async getSampleTools(count: number = 8): Promise<{ mcpName: string; description: string }[]> {
const sampleTools = await this.orchestrator.find('', count);
const mcpSet = new Set<string>();
const samples: { mcpName: string; description: string }[] = [];
for (const tool of sampleTools) {
if (!mcpSet.has(tool.mcpName)) {
mcpSet.add(tool.mcpName);
samples.push({
mcpName: tool.mcpName,
description: tool.mcpName // TODO: Get from MCP server info
});
}
}
return samples;
}
}
```
--------------------------------------------------------------------------------
/test/orchestrator-simple-branches.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Simple Orchestrator Branch Coverage Tests
* Target key uncovered branches without complex mocking
*/
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { NCPOrchestrator } from '../src/orchestrator/ncp-orchestrator';
import * as fs from 'fs';
jest.mock('fs');
describe('Orchestrator Simple Branch Tests', () => {
let orchestrator: NCPOrchestrator;
const mockFs = fs as jest.Mocked<typeof fs>;
beforeEach(() => {
jest.clearAllMocks();
orchestrator = new NCPOrchestrator('test');
mockFs.existsSync.mockReturnValue(false);
});
describe('Error Path Coverage', () => {
it('should handle MCP not configured error', async () => {
// Set up minimal profile
const emptyProfile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(emptyProfile) as any);
await orchestrator.initialize();
// Try to run tool from unconfigured MCP - should trigger line 419
const result = await orchestrator.run('nonexistent:tool', {});
expect(result.success).toBe(false);
expect(result.error).toContain('not found');
});
it('should handle initialization with no profile', async () => {
// Profile file doesn't exist
mockFs.existsSync.mockReturnValue(false);
// Should not throw
await expect(orchestrator.initialize()).resolves.not.toThrow();
});
it('should handle find with empty query', async () => {
const profile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(profile) as any);
await orchestrator.initialize();
// Empty query should return empty results (line 276-277)
const results = await orchestrator.find('', 5);
expect(Array.isArray(results)).toBe(true);
});
it('should handle getAllResources with no MCPs', async () => {
const profile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(profile) as any);
await orchestrator.initialize();
// Should return empty array
const resources = await orchestrator.getAllResources();
expect(Array.isArray(resources)).toBe(true);
expect(resources).toEqual([]);
});
it('should handle tool execution with invalid format', async () => {
const profile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(profile) as any);
await orchestrator.initialize();
// Should handle invalid tool format
const result = await orchestrator.run('invalid-format', {});
expect(result.success).toBe(false);
});
it('should handle getAllPrompts with no MCPs', async () => {
const profile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(profile) as any);
await orchestrator.initialize();
// Should return empty array
const prompts = await orchestrator.getAllPrompts();
expect(Array.isArray(prompts)).toBe(true);
expect(prompts).toEqual([]);
});
it('should handle multiple initialization calls safely', async () => {
const profile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(profile) as any);
// Multiple calls should be safe
await orchestrator.initialize();
await orchestrator.initialize();
await orchestrator.initialize();
// Should not throw
expect(true).toBe(true);
});
it('should handle cleanup gracefully', async () => {
// Should not throw even without initialization
await expect(orchestrator.cleanup()).resolves.not.toThrow();
});
});
describe('Cache Edge Cases', () => {
it('should handle corrupted cache file', async () => {
const profile = { name: 'test', mcpServers: {} };
// Profile exists but cache is corrupted
mockFs.existsSync.mockImplementation((path: any) => {
return path.toString().includes('.json');
});
mockFs.readFileSync.mockImplementation((path: any) => {
if (path.toString().includes('profiles')) {
return JSON.stringify(profile) as any;
} else {
return 'corrupted cache data' as any;
}
});
// Should handle corrupted cache gracefully
await expect(orchestrator.initialize()).resolves.not.toThrow();
});
it('should handle cache save failure', async () => {
const profile = { name: 'test', mcpServers: {} };
mockFs.existsSync.mockReturnValue(true);
mockFs.readFileSync.mockReturnValue(JSON.stringify(profile) as any);
// Mock writeFileSync to throw
mockFs.writeFileSync.mockImplementation(() => {
throw new Error('Write failed');
});
// Should handle write failure gracefully
await expect(orchestrator.initialize()).resolves.not.toThrow();
});
});
});
```
--------------------------------------------------------------------------------
/src/utils/update-checker.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Update Checker for NCP
* Checks for new versions and notifies users
*/
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
import { join } from 'path';
import { homedir } from 'os';
import chalk from 'chalk';
import { version as packageVersion, packageName } from './version.js';
interface UpdateCheckResult {
hasUpdate: boolean;
currentVersion: string;
latestVersion?: string;
updateAvailable?: boolean;
}
interface UpdateCache {
lastCheck: number;
latestVersion: string;
notificationShown: boolean;
}
export class UpdateChecker {
private packageVersion: string;
private packageName: string;
private cacheFile: string;
private readonly checkInterval = 24 * 60 * 60 * 1000; // 24 hours
constructor() {
// Use package info from module-level constants (read from package.json)
this.packageName = packageName;
this.packageVersion = packageVersion;
// Cache file location
const ncpDir = join(homedir(), '.ncp');
if (!existsSync(ncpDir)) {
mkdirSync(ncpDir, { recursive: true });
}
this.cacheFile = join(ncpDir, 'update-cache.json');
}
private loadCache(): UpdateCache | null {
try {
if (!existsSync(this.cacheFile)) {
return null;
}
return JSON.parse(readFileSync(this.cacheFile, 'utf8'));
} catch {
return null;
}
}
private saveCache(cache: UpdateCache): void {
try {
writeFileSync(this.cacheFile, JSON.stringify(cache, null, 2));
} catch {
// Ignore cache write errors
}
}
private async fetchLatestVersion(): Promise<string | null> {
try {
// Add timeout to prevent hanging
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000); // 3 second timeout
const response = await fetch(`https://registry.npmjs.org/${this.packageName}/latest`, {
signal: controller.signal
});
clearTimeout(timeout);
if (!response.ok) {
return null;
}
const data = await response.json();
return data.version || null;
} catch {
return null;
}
}
private compareVersions(current: string, latest: string): boolean {
// Simple semantic version comparison
const parseVersion = (v: string) => v.split('.').map(num => parseInt(num, 10));
const currentParts = parseVersion(current);
const latestParts = parseVersion(latest);
for (let i = 0; i < Math.max(currentParts.length, latestParts.length); i++) {
const currentPart = currentParts[i] || 0;
const latestPart = latestParts[i] || 0;
if (latestPart > currentPart) return true;
if (latestPart < currentPart) return false;
}
return false;
}
async checkForUpdates(forceCheck = false): Promise<UpdateCheckResult> {
const cache = this.loadCache();
const now = Date.now();
// Check if we need to fetch (force check or cache expired)
const shouldCheck = forceCheck ||
!cache ||
(now - cache.lastCheck) > this.checkInterval;
let latestVersion = cache?.latestVersion;
if (shouldCheck) {
const fetchedVersion = await this.fetchLatestVersion();
if (fetchedVersion) {
latestVersion = fetchedVersion;
// Save to cache
this.saveCache({
lastCheck: now,
latestVersion: fetchedVersion,
notificationShown: false
});
}
}
const hasUpdate = latestVersion ? this.compareVersions(this.packageVersion, latestVersion) : false;
return {
hasUpdate,
currentVersion: this.packageVersion,
latestVersion,
updateAvailable: hasUpdate
};
}
async showUpdateNotification(): Promise<void> {
const cache = this.loadCache();
if (cache?.notificationShown) {
return; // Already shown for this version
}
const result = await this.checkForUpdates();
if (result.hasUpdate && result.latestVersion) {
console.log();
console.log(chalk.yellow('📦 Update Available!'));
console.log(chalk.dim(` Current: ${result.currentVersion}`));
console.log(chalk.green(` Latest: ${result.latestVersion}`));
console.log();
console.log(chalk.cyan(' Run: npm install -g @portel/ncp@latest'));
console.log(chalk.dim(' Or: ncp update'));
console.log();
// Mark notification as shown
if (cache) {
cache.notificationShown = true;
this.saveCache(cache);
}
}
}
async performUpdate(): Promise<boolean> {
try {
const { spawn } = await import('child_process');
console.log(chalk.blue('🔄 Updating NCP...'));
return new Promise((resolve) => {
const updateProcess = spawn('npm', ['install', '-g', '@portel/ncp@latest'], {
stdio: 'inherit'
});
updateProcess.on('close', (code) => {
if (code === 0) {
console.log(chalk.green('✅ NCP updated successfully!'));
console.log(chalk.dim(' Restart your terminal or run: source ~/.bashrc'));
resolve(true);
} else {
console.log(chalk.red('❌ Update failed. Please try manually:'));
console.log(chalk.dim(' npm install -g @portel/ncp@latest'));
resolve(false);
}
});
});
} catch (error) {
console.log(chalk.red('❌ Update failed:'), error);
return false;
}
}
}
```
--------------------------------------------------------------------------------
/scripts/cleanup/scan-repository.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const PATTERNS = {
aiGenerated: [
/\.prd\.md$/,
/\.draft\.md$/,
/\.ai\.md$/,
/\.notes\.md$/,
/\.temp\.md$/,
/^2025-.*\.txt$/, // Date-prefixed AI exports
],
testFiles: [
/^test-.*\.js$/,
/\.test\.js$/,
/\.script\.js$/
],
backups: [
/\.backup\./,
/\.old$/,
/~$/,
/\.disabled$/
],
misplaced: [
// Files that should be in docs/ but are in root
/^TESTING\.md$/,
/^MCP_EXPANSION_SUMMARY\.md$/,
/^mcp-expansion-strategy\.md$/
],
local: [
/\.local\./,
/^\.claude\.local\.md$/,
/^CLAUDE\.local\.md$/
]
};
function scanDirectory(dir, ignore = ['node_modules', 'dist', '.git', '.ncp']) {
const issues = [];
function scan(currentPath) {
try {
const files = fs.readdirSync(currentPath);
for (const file of files) {
const fullPath = path.join(currentPath, file);
const relativePath = path.relative(process.cwd(), fullPath);
if (ignore.some(i => relativePath.includes(i))) continue;
if (fs.statSync(fullPath).isDirectory()) {
scan(fullPath);
} else {
// Check against patterns
for (const [category, patterns] of Object.entries(PATTERNS)) {
if (patterns.some(p => p.test(file))) {
// Only flag files in root for certain categories
const isRoot = path.dirname(relativePath) === '.';
if (category === 'aiGenerated' || category === 'testFiles' || category === 'misplaced') {
if (isRoot) {
issues.push({
category,
file: relativePath,
action: getRecommendedAction(category, file)
});
}
} else {
issues.push({
category,
file: relativePath,
action: getRecommendedAction(category, file)
});
}
}
}
// Check for misplaced files in specific directories
if (relativePath.startsWith('scripts/') && file.endsWith('.md')) {
issues.push({
category: 'misplaced',
file: relativePath,
action: 'Move to docs/ with appropriate sub-extension'
});
}
// Check test directory for non-test files
const validTestExtensions = [
'.test.ts', '.test.js', '.test.cjs', '.test.mjs',
'.spec.ts', '.spec.js', '.spec.cjs', '.spec.mjs',
'.ts', '.js', '.cjs', '.mjs',
'.sh', '.bash', // Shell test scripts
'.json', '.yaml', '.yml' // Config files for mock data
];
const isMockDirectory = relativePath.includes('/mock-') || relativePath.includes('/mocks/');
const isValidTestFile = validTestExtensions.some(ext => file.endsWith(ext)) || isMockDirectory;
if (relativePath.startsWith('test/') && !isValidTestFile) {
issues.push({
category: 'misplaced',
file: relativePath,
action: 'Non-test file in test directory'
});
}
}
}
} catch (error) {
console.warn(`Warning: Could not scan ${currentPath}: ${error.message}`);
}
}
scan(dir);
return issues;
}
function getRecommendedAction(category, file) {
switch (category) {
case 'aiGenerated':
return 'Should be gitignored (use sub-extension system)';
case 'testFiles':
return 'Move to test/ directory or delete if obsolete';
case 'backups':
return 'Delete or move to backup location';
case 'misplaced':
return 'Move to appropriate directory (docs/)';
case 'local':
return 'Should be gitignored (local development only)';
default:
return 'Review and categorize appropriately';
}
}
function generateReport(issues) {
if (issues.length === 0) {
console.log('✅ Repository is clean!');
return;
}
console.log('🔍 Repository Cleanup Issues Found:\n');
// Group issues by category
const groupedIssues = issues.reduce((acc, issue) => {
if (!acc[issue.category]) acc[issue.category] = [];
acc[issue.category].push(issue);
return acc;
}, {});
Object.entries(groupedIssues).forEach(([category, categoryIssues]) => {
console.log(`\n📂 ${category.toUpperCase()} (${categoryIssues.length} issues):`);
categoryIssues.forEach(issue => {
console.log(` ❌ ${issue.file}`);
console.log(` → ${issue.action}`);
});
});
console.log(`\n📊 Summary: ${issues.length} total issues found`);
// Provide cleanup suggestions
console.log('\n💡 Quick Fix Commands:');
console.log(' # Remove test files from root:');
console.log(' rm test-*.js');
console.log(' # Move documentation to docs:');
console.log(' mv HOW-IT-WORKS.md docs/how-it-works.md');
console.log(' mv TESTING.md docs/guides/testing.md');
}
// Run scan if called directly
if (import.meta.url === `file://${process.argv[1]}`) {
const issues = scanDirectory('.');
generateReport(issues);
// Exit with error code if issues found (for CI/CD)
process.exit(issues.length > 0 ? 1 : 0);
}
export { scanDirectory, generateReport };
```
--------------------------------------------------------------------------------
/src/testing/verify-profile-scaling.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
/**
* Verify Profile Scaling with Real Data
*
* Verifies that NCP profiles are correctly configured with real MCP data
* and validates the tool count scaling across different tiers.
*/
import * as fs from 'fs/promises';
import * as path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
interface ProfileMetadata {
name: string;
description: string;
mcpCount: number;
totalTools: number;
targetCount: number;
actualCount: number;
}
async function verifyProfileScaling(): Promise<void> {
console.log('🔍 Verifying NCP Profile Scaling with Real Data');
console.log('=' .repeat(50));
// Load real MCP definitions
const definitionsPath = path.join(__dirname, 'real-mcp-definitions.json');
const definitionsData = await fs.readFile(definitionsPath, 'utf-8');
const definitions = JSON.parse(definitionsData);
const availableMcps = Object.keys(definitions.mcps);
const totalToolsAvailable = Object.values(definitions.mcps).reduce(
(sum: number, mcp: any) => sum + Object.keys(mcp.tools).length,
0
);
console.log(`📊 Available Resources:`);
console.log(` Total MCPs: ${availableMcps.length}`);
console.log(` Total Tools: ${totalToolsAvailable}`);
console.log('');
// Check each profile
const profilesDir = path.join(__dirname, '../../.ncp/profiles');
const profileFiles = await fs.readdir(profilesDir);
const profiles: ProfileMetadata[] = [];
for (const file of profileFiles.filter(f => f.endsWith('.json'))) {
const profilePath = path.join(profilesDir, file);
const profileData = JSON.parse(await fs.readFile(profilePath, 'utf-8'));
if (profileData.mcpServers) {
const mcpNames = Object.keys(profileData.mcpServers);
let totalTools = 0;
// Calculate tools for MCPs that exist in our definitions
for (const mcpName of mcpNames) {
if (definitions.mcps[mcpName]) {
totalTools += Object.keys(definitions.mcps[mcpName].tools).length;
}
}
profiles.push({
name: profileData.name || path.basename(file, '.json'),
description: profileData.description || 'No description',
mcpCount: mcpNames.length,
totalTools: totalTools,
targetCount: profileData.metadata?.targetCount || 0,
actualCount: profileData.metadata?.actualCount || mcpNames.length
});
}
}
// Sort profiles by tool count
profiles.sort((a, b) => b.totalTools - a.totalTools);
console.log('📋 Profile Analysis:');
console.log('');
for (const profile of profiles) {
const toolsPerMcp = profile.totalTools > 0 ? (profile.totalTools / profile.mcpCount).toFixed(1) : '0';
const targetAchieved = profile.targetCount > 0 ?
Math.round((profile.totalTools / (profile.targetCount * 4.6)) * 100) : 100; // Assuming ~4.6 tools per MCP average
console.log(`🎯 ${profile.name.toUpperCase()}`);
console.log(` Description: ${profile.description}`);
console.log(` MCPs: ${profile.mcpCount} (target: ${profile.targetCount || 'N/A'})`);
console.log(` Tools: ${profile.totalTools} (${toolsPerMcp} per MCP)`);
if (profile.targetCount > 0) {
console.log(` Target Achievement: ${targetAchieved}% (${profile.totalTools}/${profile.targetCount * 4.6} estimated tools)`);
}
console.log('');
}
// Scaling verification
console.log('⚖️ Scaling Verification:');
console.log('');
const tier10 = profiles.find(p => p.name === 'tier-10');
const tier100 = profiles.find(p => p.name === 'tier-100');
const tier1000 = profiles.find(p => p.name === 'tier-1000');
if (tier10 && tier100 && tier1000) {
const scalingFactor10to100 = tier100.totalTools / tier10.totalTools;
const scalingFactor100to1000 = tier1000.totalTools / tier100.totalTools;
console.log(`✅ Tier-10: ${tier10.totalTools} tools (${tier10.mcpCount} MCPs)`);
console.log(`✅ Tier-100: ${tier100.totalTools} tools (${tier100.mcpCount} MCPs) - ${scalingFactor10to100.toFixed(1)}x scaling`);
console.log(`✅ Tier-1000: ${tier1000.totalTools} tools (${tier1000.mcpCount} MCPs) - ${scalingFactor100to1000.toFixed(1)}x scaling`);
console.log('');
// Assessment
if (tier100.totalTools >= 100) {
console.log('🎉 EXCELLENT: Tier-100 achieves 100+ tools as intended!');
} else if (tier100.totalTools >= 75) {
console.log('✅ GOOD: Tier-100 provides substantial tool coverage.');
} else {
console.log('⚠️ LIMITED: Tier-100 provides basic tool coverage.');
}
if (scalingFactor10to100 > 1.5) {
console.log('✅ Proper scaling between tiers maintained.');
} else {
console.log('⚠️ Limited scaling between tiers - more MCPs needed.');
}
}
console.log('');
console.log('💡 Recommendations:');
if (totalToolsAvailable >= 100) {
console.log(' ✅ Sufficient tools available for comprehensive testing');
} else {
console.log(' 📈 Consider adding more MCPs to reach 100+ tools');
}
if (availableMcps.length >= 20) {
console.log(' ✅ Good variety of MCP types for diverse testing');
} else {
console.log(' 🔄 Consider diversifying MCP categories');
}
console.log('');
console.log('🚀 Ready for multi-tier semantic enhancement testing!');
}
// CLI interface
if (import.meta.url === `file://${process.argv[1]}`) {
verifyProfileScaling().catch(error => {
console.error('❌ Verification failed:', error.message);
process.exit(1);
});
}
```
--------------------------------------------------------------------------------
/src/auth/oauth-device-flow.ts:
--------------------------------------------------------------------------------
```typescript
/**
* OAuth 2.0 Device Authorization Grant (Device Flow)
* RFC 8628: https://tools.ietf.org/html/rfc8628
*
* Used for CLI and non-browser environments where user authenticates
* on a separate device (phone, browser on another machine, etc.)
*/
import { logger } from '../utils/logger.js';
export interface DeviceAuthResponse {
device_code: string;
user_code: string;
verification_uri: string;
verification_uri_complete?: string; // Optional: includes code in URL
expires_in: number;
interval: number; // Polling interval in seconds
}
export interface TokenResponse {
access_token: string;
refresh_token?: string;
expires_in: number;
token_type: string;
scope?: string;
}
export interface OAuthConfig {
clientId: string;
clientSecret?: string; // Optional for public clients
deviceAuthUrl: string; // Device authorization endpoint
tokenUrl: string; // Token endpoint
scopes?: string[];
}
export class DeviceFlowAuthenticator {
constructor(private config: OAuthConfig) {}
/**
* Complete OAuth Device Flow authentication
*/
async authenticate(): Promise<TokenResponse> {
logger.debug('Starting OAuth Device Flow...');
// Step 1: Request device code
const deviceAuth = await this.requestDeviceCode();
// Step 2: Display user instructions
this.displayUserInstructions(deviceAuth);
// Step 3: Poll for authorization
const token = await this.pollForToken(deviceAuth);
logger.debug('OAuth Device Flow completed successfully');
return token;
}
/**
* Step 1: Request device and user codes from authorization server
*/
private async requestDeviceCode(): Promise<DeviceAuthResponse> {
const params = new URLSearchParams({
client_id: this.config.clientId,
scope: this.config.scopes?.join(' ') || ''
});
logger.debug(`Requesting device code from ${this.config.deviceAuthUrl}`);
const response = await fetch(this.config.deviceAuthUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
if (!response.ok) {
const error = await response.text();
throw new Error(`Device authorization request failed: ${response.status} ${error}`);
}
const data: DeviceAuthResponse = await response.json();
logger.debug(`Device code received: ${data.device_code.substring(0, 10)}...`);
logger.debug(`User code: ${data.user_code}`);
return data;
}
/**
* Step 2: Display instructions to user
*/
private displayUserInstructions(auth: DeviceAuthResponse): void {
console.log('\n┌─────────────────────────────────────────┐');
console.log('│ 🔐 OAuth Authentication Required │');
console.log('└─────────────────────────────────────────┘\n');
if (auth.verification_uri_complete) {
// Complete URI includes the user code
console.log('📱 Visit this URL on any device:\n');
console.log(` ${auth.verification_uri_complete}\n`);
console.log(' (Code is already included in the URL)\n');
} else {
// Separate URI and code
console.log(`📱 Visit: ${auth.verification_uri}\n`);
console.log(`🔑 Enter code: ${auth.user_code}\n`);
}
const expiresInMinutes = Math.floor(auth.expires_in / 60);
console.log(`⏱️ Code expires in ${expiresInMinutes} minutes\n`);
console.log('⏳ Waiting for authorization...');
}
/**
* Step 3: Poll token endpoint until user authorizes
*/
private async pollForToken(auth: DeviceAuthResponse): Promise<TokenResponse> {
const expiresAt = Date.now() + (auth.expires_in * 1000);
const interval = auth.interval * 1000; // Convert to ms
let pollInterval = interval;
while (Date.now() < expiresAt) {
await this.sleep(pollInterval);
const params = new URLSearchParams({
grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
device_code: auth.device_code,
client_id: this.config.clientId
});
// Add client secret if provided (for confidential clients)
if (this.config.clientSecret) {
params.set('client_secret', this.config.clientSecret);
}
logger.debug('Polling token endpoint...');
const response = await fetch(this.config.tokenUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
const data = await response.json();
// Success!
if (data.access_token) {
console.log('\n✅ Authentication successful!\n');
return data;
}
// Handle errors according to RFC 8628
if (data.error === 'authorization_pending') {
// User hasn't authorized yet, continue polling
process.stdout.write('.');
continue;
}
if (data.error === 'slow_down') {
// Server requests slower polling
pollInterval += 5000;
logger.debug(`Slowing down polling interval to ${pollInterval}ms`);
process.stdout.write('.');
continue;
}
if (data.error === 'expired_token') {
throw new Error('Authorization code expired. Please try again.');
}
if (data.error === 'access_denied') {
throw new Error('Authorization denied by user.');
}
// Other errors
throw new Error(`OAuth error: ${data.error} - ${data.error_description || 'Unknown error'}`);
}
throw new Error('Authentication timed out. Please try again.');
}
private sleep(ms: number): Promise<void> {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
```
--------------------------------------------------------------------------------
/test/mcp-wrapper.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Unit Tests - MCPWrapper
* Tests wrapper script generation, log management, and directory handling
* Adapted from commercial NCP test patterns
*/
import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
// Mock filesystem and os modules completely
jest.mock('fs', () => ({
existsSync: jest.fn(),
mkdirSync: jest.fn(),
readdirSync: jest.fn(),
statSync: jest.fn(),
unlinkSync: jest.fn(),
writeFileSync: jest.fn()
}));
jest.mock('os', () => ({
homedir: jest.fn(),
tmpdir: jest.fn()
}));
describe('MCPWrapper', () => {
let mcpWrapper: any;
let mockFs: any;
let mockOs: any;
beforeEach(async () => {
jest.clearAllMocks();
jest.resetModules();
// Get fresh mocked modules
mockFs = await import('fs');
mockOs = await import('os');
// Setup default mock implementations
mockFs.existsSync.mockReturnValue(true);
mockFs.mkdirSync.mockReturnValue(undefined);
mockFs.readdirSync.mockReturnValue([]);
mockFs.statSync.mockReturnValue({ mtime: new Date() });
mockFs.writeFileSync.mockReturnValue(undefined);
mockOs.homedir.mockReturnValue('/mock/home');
mockOs.tmpdir.mockReturnValue('/mock/tmp');
// Import MCPWrapper after mocking
const { MCPWrapper } = await import('../src/utils/mcp-wrapper.js');
mcpWrapper = new MCPWrapper();
});
afterEach(() => {
jest.clearAllMocks();
});
describe('initialization', () => {
it('should create MCP wrapper successfully', () => {
expect(mcpWrapper).toBeDefined();
});
it('should ensure directories exist during creation', () => {
expect(mockFs.existsSync).toHaveBeenCalled();
expect(mockOs.homedir).toHaveBeenCalled();
expect(mockOs.tmpdir).toHaveBeenCalled();
});
it('should create missing directories', async () => {
mockFs.existsSync.mockReturnValue(false);
const { MCPWrapper } = await import('../src/utils/mcp-wrapper.js');
new MCPWrapper();
expect(mockFs.mkdirSync).toHaveBeenCalled();
});
});
describe('wrapper creation', () => {
it('should create wrapper script for MCP server', () => {
const result = mcpWrapper.createWrapper('test-mcp', 'node', ['script.js']);
expect(result).toBeDefined();
expect(result.command).toBeDefined();
expect(Array.isArray(result.args)).toBe(true);
expect(mockFs.writeFileSync).toHaveBeenCalled();
});
it('should handle different command formats', () => {
const result1 = mcpWrapper.createWrapper('test1', 'node', ['script.js']);
const result2 = mcpWrapper.createWrapper('test2', 'python', ['-m', 'module']);
expect(result1.command).toBeDefined();
expect(result2.command).toBeDefined();
});
it('should handle commands without arguments', () => {
const result = mcpWrapper.createWrapper('test', 'echo');
expect(result).toBeDefined();
expect(result.command).toBeDefined();
});
});
describe('log management', () => {
it('should clean up old logs during initialization', async () => {
// Mock old files with correct naming pattern (mcp-*.log)
mockFs.readdirSync.mockReturnValue(['mcp-old-server-2023w01.log', 'mcp-new-server-2024w52.log'] as any);
mockFs.statSync.mockReturnValueOnce({
mtime: new Date(Date.now() - 8 * 24 * 60 * 60 * 1000) // 8 days old
} as any).mockReturnValueOnce({
mtime: new Date() // New file
} as any);
const { MCPWrapper } = await import('../src/utils/mcp-wrapper.js');
new MCPWrapper();
expect(mockFs.unlinkSync).toHaveBeenCalled();
});
it('should handle log cleanup errors gracefully', async () => {
mockFs.readdirSync.mockImplementation(() => {
throw new Error('Read dir failed');
});
const { MCPWrapper } = await import('../src/utils/mcp-wrapper.js');
expect(() => new MCPWrapper()).not.toThrow();
});
});
describe('edge cases', () => {
it('should handle empty MCP name', () => {
const result = mcpWrapper.createWrapper('', 'echo');
expect(result).toBeDefined();
});
it('should handle special characters in MCP name', () => {
const result = mcpWrapper.createWrapper('test-mcp_123', 'echo');
expect(result).toBeDefined();
});
});
describe('log file utilities', () => {
it('should get log file path for MCP', () => {
// Test getLogFile method (lines 182-184)
const logFile = mcpWrapper.getLogFile('test-mcp');
expect(typeof logFile).toBe('string');
expect(logFile).toContain('test-mcp');
});
it('should list all log files', () => {
// Test listLogFiles method (lines 189-198)
mockFs.readdirSync.mockReturnValue(['mcp-server1.log', 'mcp-server2.log', 'other-file.txt'] as any);
const logFiles = mcpWrapper.listLogFiles();
expect(Array.isArray(logFiles)).toBe(true);
expect(logFiles.length).toBe(2); // Should filter only mcp-*.log files
});
it('should handle missing log directory', () => {
// Test lines 191-192: directory doesn't exist
mockFs.existsSync.mockReturnValue(false);
const logFiles = mcpWrapper.listLogFiles();
expect(Array.isArray(logFiles)).toBe(true);
expect(logFiles.length).toBe(0);
});
it('should handle log directory read errors', () => {
// Test lines 195-196: catch block
mockFs.existsSync.mockReturnValue(true);
mockFs.readdirSync.mockImplementation(() => {
throw new Error('Cannot read directory');
});
const logFiles = mcpWrapper.listLogFiles();
expect(Array.isArray(logFiles)).toBe(true);
expect(logFiles.length).toBe(0);
});
});
});
```
--------------------------------------------------------------------------------
/src/auth/token-store.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Secure token storage with encryption for OAuth tokens
*
* Stores tokens per MCP server with automatic refresh and expiration handling
* Uses AES-256-CBC encryption with OS keychain for encryption key
*/
import * as crypto from 'crypto';
import * as fs from 'fs';
import * as path from 'path';
import { logger } from '../utils/logger.js';
import type { TokenResponse } from './oauth-device-flow.js';
const ALGORITHM = 'aes-256-cbc';
const TOKEN_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.ncp', 'tokens');
export interface StoredToken {
access_token: string;
refresh_token?: string;
expires_at: number; // Unix timestamp in milliseconds
token_type: string;
scope?: string;
}
export class TokenStore {
private encryptionKey: Buffer;
constructor() {
this.encryptionKey = this.getOrCreateEncryptionKey();
this.ensureTokenDir();
}
/**
* Store encrypted token for an MCP server
*/
async storeToken(mcpName: string, tokenResponse: TokenResponse): Promise<void> {
const expiresAt = Date.now() + (tokenResponse.expires_in * 1000);
const storedToken: StoredToken = {
access_token: tokenResponse.access_token,
refresh_token: tokenResponse.refresh_token,
expires_at: expiresAt,
token_type: tokenResponse.token_type,
scope: tokenResponse.scope
};
const encrypted = this.encrypt(JSON.stringify(storedToken));
const tokenPath = this.getTokenPath(mcpName);
await fs.promises.writeFile(tokenPath, encrypted, { mode: 0o600 });
logger.debug(`Token stored for ${mcpName}, expires at ${new Date(expiresAt).toISOString()}`);
}
/**
* Get valid token for an MCP server
* Returns null if token doesn't exist or is expired without refresh token
*/
async getToken(mcpName: string): Promise<StoredToken | null> {
const tokenPath = this.getTokenPath(mcpName);
if (!fs.existsSync(tokenPath)) {
logger.debug(`No token found for ${mcpName}`);
return null;
}
try {
const encrypted = await fs.promises.readFile(tokenPath, 'utf-8');
const decrypted = this.decrypt(encrypted);
const token: StoredToken = JSON.parse(decrypted);
// Check expiration (with 5 minute buffer)
const expirationBuffer = 5 * 60 * 1000; // 5 minutes
if (Date.now() + expirationBuffer >= token.expires_at) {
logger.debug(`Token for ${mcpName} expired or expiring soon`);
return null; // Token refresh should be handled by caller
}
return token;
} catch (error) {
logger.error(`Failed to read token for ${mcpName}:`, error);
return null;
}
}
/**
* Check if valid token exists for an MCP server
*/
async hasValidToken(mcpName: string): Promise<boolean> {
const token = await this.getToken(mcpName);
return token !== null;
}
/**
* Delete token for an MCP server
*/
async deleteToken(mcpName: string): Promise<void> {
const tokenPath = this.getTokenPath(mcpName);
if (fs.existsSync(tokenPath)) {
await fs.promises.unlink(tokenPath);
logger.debug(`Token deleted for ${mcpName}`);
}
}
/**
* List all MCPs with stored tokens
*/
async listTokens(): Promise<string[]> {
if (!fs.existsSync(TOKEN_DIR)) {
return [];
}
const files = await fs.promises.readdir(TOKEN_DIR);
return files
.filter(f => f.endsWith('.token'))
.map(f => f.replace('.token', ''));
}
/**
* Encrypt data using AES-256-CBC
*/
private encrypt(text: string): string {
const iv = crypto.randomBytes(16);
const cipher = crypto.createCipheriv(ALGORITHM, this.encryptionKey, iv);
let encrypted = cipher.update(text, 'utf8', 'hex');
encrypted += cipher.final('hex');
// Return IV + encrypted data
return iv.toString('hex') + ':' + encrypted;
}
/**
* Decrypt data using AES-256-CBC
*/
private decrypt(text: string): string {
const parts = text.split(':');
const iv = Buffer.from(parts[0], 'hex');
const encrypted = parts[1];
const decipher = crypto.createDecipheriv(ALGORITHM, this.encryptionKey, iv);
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
return decrypted;
}
/**
* Get or create encryption key (32 bytes for AES-256)
* Stored in ~/.ncp/encryption.key with restricted permissions
*/
private getOrCreateEncryptionKey(): Buffer {
const keyPath = path.join(process.env.HOME || process.env.USERPROFILE || '', '.ncp', 'encryption.key');
const keyDir = path.dirname(keyPath);
if (!fs.existsSync(keyDir)) {
fs.mkdirSync(keyDir, { recursive: true, mode: 0o700 });
}
if (fs.existsSync(keyPath)) {
const key = fs.readFileSync(keyPath);
if (key.length !== 32) {
throw new Error('Invalid encryption key length');
}
return key;
}
// Generate new key
const key = crypto.randomBytes(32);
fs.writeFileSync(keyPath, key, { mode: 0o600 });
logger.debug('Generated new encryption key');
return key;
}
/**
* Ensure token directory exists with proper permissions
*/
private ensureTokenDir(): void {
if (!fs.existsSync(TOKEN_DIR)) {
fs.mkdirSync(TOKEN_DIR, { recursive: true, mode: 0o700 });
}
}
/**
* Get file path for MCP token
*/
private getTokenPath(mcpName: string): string {
// Sanitize MCP name for filesystem
const safeName = mcpName.replace(/[^a-zA-Z0-9-_]/g, '_');
return path.join(TOKEN_DIR, `${safeName}.token`);
}
}
// Singleton instance
let tokenStoreInstance: TokenStore | null = null;
export function getTokenStore(): TokenStore {
if (!tokenStoreInstance) {
tokenStoreInstance = new TokenStore();
}
return tokenStoreInstance;
}
```
--------------------------------------------------------------------------------
/src/services/registry-client.ts:
--------------------------------------------------------------------------------
```typescript
/**
* MCP Registry Client
*
* Interacts with the official MCP Registry API for server discovery
* API Docs: https://registry.modelcontextprotocol.io/
*/
import { logger } from '../utils/logger.js';
export interface RegistryServer {
server: {
name: string;
description: string;
version: string;
repository?: {
url: string;
type?: string;
};
packages?: Array<{
identifier: string;
version: string;
runtimeHint?: string;
environmentVariables?: Array<{
name: string;
description?: string;
isRequired?: boolean;
default?: string;
}>;
}>;
};
_meta?: {
'io.modelcontextprotocol.registry/official'?: {
status: string;
};
};
}
export interface ServerSearchResult {
server: {
name: string;
description: string;
version: string;
packages?: Array<{
identifier: string;
version: string;
runtimeHint?: string;
}>;
};
_meta?: {
'io.modelcontextprotocol.registry/official'?: {
status: string;
};
};
}
export interface RegistryMCPCandidate {
number: number;
name: string;
displayName: string;
description: string;
version: string;
command: string;
args: string[];
envVars?: Array<{
name: string;
description?: string;
isRequired?: boolean;
default?: string;
}>;
downloadCount?: number;
status?: string;
}
export class RegistryClient {
private baseURL = 'https://registry.modelcontextprotocol.io/v0';
private cache: Map<string, { data: any; timestamp: number }> = new Map();
private readonly CACHE_TTL = 5 * 60 * 1000; // 5 minutes
/**
* Search for MCP servers in the registry
*/
async search(query: string, limit: number = 50): Promise<ServerSearchResult[]> {
try {
const cacheKey = `search:${query}:${limit}`;
const cached = this.getFromCache(cacheKey);
if (cached) return cached;
logger.debug(`Searching registry for: ${query}`);
const response = await fetch(`${this.baseURL}/servers?limit=${limit}`);
if (!response.ok) {
throw new Error(`Registry API error: ${response.statusText}`);
}
const data = await response.json();
// Filter results by query (search in name and description)
const lowerQuery = query.toLowerCase();
const filtered = (data.servers || []).filter((s: ServerSearchResult) =>
s.server.name.toLowerCase().includes(lowerQuery) ||
s.server.description?.toLowerCase().includes(lowerQuery)
);
this.setCache(cacheKey, filtered);
logger.debug(`Found ${filtered.length} results for: ${query}`);
return filtered;
} catch (error: any) {
logger.error(`Registry search failed: ${error.message}`);
throw new Error(`Failed to search registry: ${error.message}`);
}
}
/**
* Get detailed information about a specific server
*/
async getServer(serverName: string): Promise<RegistryServer> {
try {
const cacheKey = `server:${serverName}`;
const cached = this.getFromCache(cacheKey);
if (cached) return cached;
const encoded = encodeURIComponent(serverName);
const response = await fetch(`${this.baseURL}/servers/${encoded}`);
if (!response.ok) {
throw new Error(`Server not found: ${serverName}`);
}
const data = await response.json();
this.setCache(cacheKey, data);
return data;
} catch (error: any) {
logger.error(`Failed to get server ${serverName}: ${error.message}`);
throw new Error(`Failed to get server: ${error.message}`);
}
}
/**
* Search and format results as numbered candidates for user selection
*/
async searchForSelection(query: string): Promise<RegistryMCPCandidate[]> {
const results = await this.search(query, 20); // Get up to 20 results
return results.map((result, index) => {
const pkg = result.server.packages?.[0];
const shortName = this.extractShortName(result.server.name);
return {
number: index + 1,
name: result.server.name,
displayName: shortName,
description: result.server.description || 'No description',
version: result.server.version,
command: pkg?.runtimeHint || 'npx',
args: pkg ? [pkg.identifier] : [],
status: result._meta?.['io.modelcontextprotocol.registry/official']?.status
};
});
}
/**
* Get detailed info for selected MCPs (including env vars)
*/
async getDetailedInfo(serverName: string): Promise<{
command: string;
args: string[];
envVars?: Array<{
name: string;
description?: string;
isRequired?: boolean;
default?: string;
}>;
}> {
const server = await this.getServer(serverName);
const pkg = server.server.packages?.[0];
if (!pkg) {
throw new Error(`No package information available for ${serverName}`);
}
return {
command: pkg.runtimeHint || 'npx',
args: [pkg.identifier],
envVars: pkg.environmentVariables
};
}
/**
* Extract short name from full registry name
* io.github.modelcontextprotocol/server-filesystem → server-filesystem
*/
private extractShortName(fullName: string): string {
const parts = fullName.split('/');
return parts[parts.length - 1] || fullName;
}
/**
* Get from cache if not expired
*/
private getFromCache(key: string): any | null {
const cached = this.cache.get(key);
if (cached && Date.now() - cached.timestamp < this.CACHE_TTL) {
return cached.data;
}
return null;
}
/**
* Set cache with timestamp
*/
private setCache(key: string, data: any): void {
this.cache.set(key, {
data,
timestamp: Date.now()
});
}
/**
* Clear cache
*/
clearCache(): void {
this.cache.clear();
}
}
```
--------------------------------------------------------------------------------
/test/mcp-timeout-scenarios.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* MCP Timeout Scenario Tests
* Tests that would have caught the blocking bug during indexing
*/
import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
import { MCPServer } from '../src/server/mcp-server.js';
describe('MCP Timeout Prevention Tests', () => {
let server: MCPServer;
beforeEach(() => {
server = new MCPServer('test', false);
});
afterEach(async () => {
if (server) {
await server.cleanup?.();
}
});
describe('Indexing Timeout Scenarios', () => {
it('should never timeout on tools/list during heavy indexing', async () => {
// Simulate the exact scenario where the bug occurred:
// Large profile with many MCPs being indexed
// Don't await initialization (simulating background indexing)
const initPromise = server.initialize();
// Multiple rapid-fire tools/list requests (like Claude Desktop does)
const requests = Array.from({ length: 10 }, (_, i) =>
Promise.race([
server.handleRequest({
jsonrpc: '2.0',
id: `timeout-test-${i}`,
method: 'tools/list'
}),
// Fail if any request takes more than 1 second
new Promise((_, reject) =>
setTimeout(() => reject(new Error(`Request ${i} timed out`)), 1000)
)
])
);
// All requests should complete without timeout
const responses = await Promise.all(requests);
// Verify all responses are valid
responses.forEach((response: any, i) => {
expect(response).toBeDefined();
expect(response?.result?.tools).toBeDefined();
expect(response?.id).toBe(`timeout-test-${i}`);
});
// Wait for initialization to complete
await initPromise;
});
it('should respond to initialize within 100ms even with slow indexing', async () => {
const timeout = new Promise((_, reject) =>
setTimeout(() => reject(new Error('Initialize timed out')), 100)
);
const response = Promise.resolve(server.handleRequest({
jsonrpc: '2.0',
id: 'init-timeout-test',
method: 'initialize',
params: {
protocolVersion: '2024-11-05',
capabilities: {}
}
}));
// Should complete before timeout
const result = await Promise.race([response, timeout]);
expect(result).toBeDefined();
expect((result as any).result?.serverInfo?.name).toBe('ncp');
});
it('should handle burst requests during indexing startup', async () => {
// Simulate Claude Desktop connecting and making rapid requests
const burstRequests = [
server.handleRequest({
jsonrpc: '2.0',
id: 'burst-1',
method: 'initialize',
params: { protocolVersion: '2024-11-05', capabilities: {} }
}),
server.handleRequest({
jsonrpc: '2.0',
id: 'burst-2',
method: 'tools/list'
}),
server.handleRequest({
jsonrpc: '2.0',
id: 'burst-3',
method: 'tools/list'
}),
server.handleRequest({
jsonrpc: '2.0',
id: 'burst-4',
method: 'tools/call',
params: { name: 'find', arguments: { description: 'test' } }
})
];
// Start initialization in parallel
const initPromise = server.initialize();
// All burst requests should complete quickly
const startTime = Date.now();
const results = await Promise.all(burstRequests);
const totalTime = Date.now() - startTime;
expect(totalTime).toBeLessThan(2000); // Should handle burst quickly
// Verify all responses are valid
expect(results[0]?.result?.serverInfo).toBeDefined(); // initialize
expect(results[1]?.result?.tools).toBeDefined(); // tools/list
expect(results[2]?.result?.tools).toBeDefined(); // tools/list
expect(results[3]?.result?.content).toBeDefined(); // tools/call
await initPromise;
});
});
describe('Large Profile Simulation', () => {
it('should handle tools/list with 1000+ MCP simulation', async () => {
// Create server that would index many MCPs (use 'all' profile)
const largeServer = new MCPServer('all', false);
try {
// Don't wait for full initialization
const initPromise = largeServer.initialize();
// Immediately request tools/list (the failing scenario)
const startTime = Date.now();
const response = await largeServer.handleRequest({
jsonrpc: '2.0',
id: 'large-profile-test',
method: 'tools/list'
});
const responseTime = Date.now() - startTime;
// Should respond quickly even with large profile
expect(responseTime).toBeLessThan(500);
expect(response).toBeDefined();
expect(response?.result?.tools).toBeDefined();
await initPromise;
} finally {
await largeServer.cleanup?.();
}
});
});
describe('Race Condition Tests', () => {
it('should handle concurrent initialization and requests', async () => {
// Start multiple operations simultaneously
const operations = [
server.initialize(),
server.handleRequest({
jsonrpc: '2.0',
id: 'race-1',
method: 'tools/list'
}),
server.handleRequest({
jsonrpc: '2.0',
id: 'race-2',
method: 'tools/list'
})
];
// All should complete without hanging
const results = await Promise.all(operations);
// Verify responses (skip initialization result)
expect(results[1]).toBeDefined();
expect(results[2]).toBeDefined();
expect((results[1] as any).result?.tools).toBeDefined();
expect((results[2] as any).result?.tools).toBeDefined();
});
});
});
```
--------------------------------------------------------------------------------
/test/discovery-fallback-focused.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Discovery Fallback Focused Tests - Target engine.ts lines 80-131
* These tests specifically target the fallback mechanisms
*/
import { describe, it, expect } from '@jest/globals';
import { DiscoveryEngine } from '../src/discovery/engine.js';
describe('Discovery Fallback Focus', () => {
it('should exercise similarity matching fallback', async () => {
const engine = new DiscoveryEngine();
await engine.initialize();
// Index tools with varying similarity
const tools = [
{
id: 'text:processor',
name: 'text-processor',
description: 'Process text documents and extract information'
},
{
id: 'data:analyzer',
name: 'data-analyzer',
description: 'Analyze data patterns and generate insights'
},
{
id: 'file:manager',
name: 'file-manager',
description: 'Manage files and directories on the system'
}
];
for (const tool of tools) {
await engine.indexTool(tool);
}
// Force the similarity matching path by using private method access
const result = await (engine as any).findSimilarityMatch('process documents extract');
// Should find the text processor as most similar or return null
if (result) {
expect(result.confidence).toBeGreaterThan(0.3);
}
expect(result).toBeDefined(); // Just ensure method runs
});
it('should test keyword matching fallback logic', async () => {
const engine = new DiscoveryEngine();
await engine.initialize();
// Index tools with specific keywords
await engine.indexTool({
id: 'system:monitor',
name: 'monitor',
description: 'Monitor system performance and resource usage'
});
await engine.indexTool({
id: 'network:scanner',
name: 'scanner',
description: 'Scan network connections and ports'
});
// Test keyword matching directly
const result = await (engine as any).findKeywordMatch('monitor system performance');
expect(result).toBeTruthy();
expect(result.reason).toContain('matching');
});
it('should exercise pattern matching with complex patterns', async () => {
const engine = new DiscoveryEngine();
await engine.initialize();
// Index tool with rich pattern extraction opportunities
await engine.indexTool({
id: 'advanced:operations',
name: 'advanced-operations',
description: 'Create multiple files, read directory contents, update existing resources, and delete old data'
});
// Test pattern extraction worked
const stats = engine.getStats();
expect(stats.totalPatterns).toBeGreaterThan(10); // Should extract many patterns
// Test pattern matching
const result = await (engine as any).findPatternMatch('create files');
expect(result).toBeTruthy();
});
it('should handle similarity calculation edge cases', async () => {
const engine = new DiscoveryEngine();
// Test the similarity calculation with edge cases
const similarity1 = (engine as any).calculateSimilarity('', ''); // Empty strings
expect(similarity1).toBeGreaterThanOrEqual(0); // Empty strings can be 0 or 1 depending on implementation
const similarity2 = (engine as any).calculateSimilarity('word', 'word'); // Identical
expect(similarity2).toBe(1);
const similarity3 = (engine as any).calculateSimilarity('hello world', 'world hello'); // Same words different order
expect(similarity3).toBe(1);
const similarity4 = (engine as any).calculateSimilarity('abc def', 'def ghi'); // Partial overlap
expect(similarity4).toBeGreaterThan(0);
expect(similarity4).toBeLessThan(1);
});
it('should test pattern extraction from names', async () => {
const engine = new DiscoveryEngine();
// Test pattern extraction from different name formats
const patterns1 = (engine as any).extractPatternsFromName('multi-word-tool-name');
expect(patterns1.length).toBeGreaterThan(3);
const patterns2 = (engine as any).extractPatternsFromName('camelCaseToolName');
expect(patterns2.length).toBeGreaterThan(1);
const patterns3 = (engine as any).extractPatternsFromName('simple');
expect(patterns3).toContain('simple');
});
it('should test pattern extraction from descriptions with quoted text', async () => {
const engine = new DiscoveryEngine();
// Test pattern extraction with quoted phrases
const patterns = (engine as any).extractPatternsFromDescription(
'Tool to "create new files" and (manage directories) with special operations'
);
expect(patterns).toContain('create new files');
expect(patterns.length).toBeGreaterThan(5);
});
it('should exercise findRelatedTools completely', async () => {
const engine = new DiscoveryEngine();
await engine.initialize();
// Index multiple tools with varying relationships
const tools = [
{ id: 'a:read', name: 'read', description: 'Read file contents from disk storage' },
{ id: 'b:write', name: 'write', description: 'Write file contents to disk storage' },
{ id: 'c:copy', name: 'copy', description: 'Copy files between different locations' },
{ id: 'd:math', name: 'math', description: 'Perform mathematical calculations and computations' }
];
for (const tool of tools) {
await engine.indexTool(tool);
}
// Find related tools - should find file operations as related
const related = await engine.findRelatedTools('a:read');
expect(related.length).toBeGreaterThan(0);
// Check that similarity scores are calculated
related.forEach(rel => {
expect(rel.similarity).toBeGreaterThan(0);
expect(rel.similarity).toBeLessThanOrEqual(1);
});
// Should be sorted by similarity (highest first)
for (let i = 1; i < related.length; i++) {
expect(related[i].similarity).toBeLessThanOrEqual(related[i-1].similarity);
}
});
});
```
--------------------------------------------------------------------------------
/docs/clients/perplexity.md:
--------------------------------------------------------------------------------
```markdown
# Installing NCP on Perplexity
**Status:** JSON configuration only (`.dxt` extension support coming soon)
---
## 📋 Overview
Perplexity Mac app supports MCP servers via JSON configuration. While `.dxt` drag-and-drop installation is not yet supported, you can manually configure NCP to work with Perplexity.
### What You Get:
- ✅ Access to all your MCP tools through NCP's unified interface
- ✅ Semantic search for tool discovery
- ✅ Token optimization (97% reduction in context usage)
- ⚠️ Manual configuration required (no auto-import from Perplexity yet)
---
## 🔧 Installation Steps
### 1. Install NCP via npm
```bash
npm install -g @portel/ncp
```
### 2. Add Your MCPs to NCP
Since Perplexity doesn't support auto-import yet, manually add your MCPs to NCP:
```bash
# Add popular MCPs
ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents
ncp add github npx @modelcontextprotocol/server-github
ncp add brave-search npx @modelcontextprotocol/server-brave-search
# Verify they were added
ncp list
```
### 3. Configure Perplexity
Perplexity stores its MCP configuration in:
```
~/Library/Containers/ai.perplexity.mac/Data/Documents/mcp_servers
```
This file uses a **different JSON format** than Claude Desktop (array-based, not object-based).
**Edit the file:**
```bash
# Open Perplexity's MCP config
nano ~/Library/Containers/ai.perplexity.mac/Data/Documents/mcp_servers
```
**Replace entire contents with:**
```json
{
"servers": [
{
"name": "NCP",
"enabled": true,
"connetionInfo": {
"command": "ncp",
"args": [],
"env": {}
}
}
]
}
```
> **Note:** Yes, it's spelled "connetionInfo" (not "connectionInfo") in Perplexity's format. This is how Perplexity expects it.
### 4. Restart Perplexity
1. Quit Perplexity completely
2. Reopen Perplexity
3. Start a new chat
### 5. Verify Installation
In a Perplexity chat, ask:
```
"List all available MCP tools using NCP"
```
Perplexity should use NCP's `find` tool to discover your MCPs.
---
## 🎯 Managing MCPs
### Adding More MCPs
```bash
# Add MCPs using NCP CLI
ncp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
ncp add memory npx @modelcontextprotocol/server-memory
# Verify additions
ncp list
```
### Removing MCPs
```bash
# Remove an MCP
ncp remove filesystem
# Verify removal
ncp list
```
### Testing MCPs
```bash
# Test tool discovery
ncp find "read a file"
# Test tool execution (dry run)
ncp run filesystem:read_file --params '{"path": "/tmp/test.txt"}' --dry-run
```
---
## 🆚 NCP vs Direct MCP Configuration
| Feature | With NCP | Without NCP |
|---------|----------|-------------|
| **Context Usage** | 2 tools (2.5k tokens) | 50+ tools (100k+ tokens) |
| **Tool Discovery** | Semantic search | Manual inspection |
| **Configuration** | One NCP entry | Individual entries per MCP |
| **Tool Updates** | Update NCP profile | Edit Perplexity config |
---
## 📍 Configuration File Locations
**Perplexity MCP Config:**
```
~/Library/Containers/ai.perplexity.mac/Data/Documents/mcp_servers
```
**Perplexity Extensions (dxt):**
```
~/Library/Containers/ai.perplexity.mac/Data/Documents/connectors/dxt/installed/
```
**NCP Profiles:**
```
~/.ncp/profiles/all.json
```
---
## 🐛 Troubleshooting
### NCP command not found
```bash
# Reinstall globally
npm install -g @portel/ncp
# Verify installation
ncp --version
```
### Perplexity doesn't see NCP
1. **Check config file format** - Perplexity uses array format with "connetionInfo" (note the typo)
2. **Verify NCP is in PATH** - Run `which ncp` to verify
3. **Restart Perplexity completely** - Quit, don't just close window
4. **Check Perplexity logs** - Look for MCP-related errors in Console.app
### NCP shows no MCPs
```bash
# Check NCP configuration
ncp list
# If empty, add MCPs
ncp add filesystem npx @modelcontextprotocol/server-filesystem ~/Documents
# Verify profile
cat ~/.ncp/profiles/all.json
```
### Can't edit Perplexity config (sandboxed)
Perplexity uses macOS sandboxing. If you can't edit the config file:
```bash
# Open parent directory in Finder
open ~/Library/Containers/ai.perplexity.mac/Data/Documents/
# Edit file with TextEdit or VS Code
# Make sure to save changes
```
---
## 🔮 Future: Extension Support
**Coming Soon:** `.dxt` extension support for Perplexity
When Perplexity adds `.dxt` support, you'll be able to:
- ✅ Drag and drop `ncp.dxt` for one-click installation
- ✅ Auto-import existing Perplexity MCPs
- ✅ Auto-sync on every startup
Track progress: [Perplexity MCP Documentation](https://docs.perplexity.ai/guides/mcp-server)
---
## 📝 Perplexity JSON Format Reference
### Standard Format (Claude Desktop, Cursor, etc.)
```json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "package-name"],
"env": {}
}
}
}
```
### Perplexity Format
```json
{
"servers": [
{
"name": "server-name",
"enabled": true,
"connetionInfo": {
"command": "npx",
"args": ["-y", "package-name"],
"env": {}
}
}
]
}
```
**Key differences:**
1. Uses `servers` array instead of `mcpServers` object
2. Each server has `name`, `enabled`, and `connetionInfo` fields
3. Uses "connetionInfo" (typo, not "connectionInfo")
4. Boolean `enabled` flag for each server
---
## 🚀 Next Steps
After installation, learn how to use NCP:
- **[NCP Usage Guide](../guides/how-it-works.md)** - Understanding NCP's architecture
- **[Testing Guide](../guides/testing.md)** - Verify everything works
- **[Main README](../../README.md)** - Full documentation
---
## 🤝 Need Help?
- **GitHub Issues:** [Report bugs or request features](https://github.com/portel-dev/ncp/issues)
- **GitHub Discussions:** [Ask questions and share tips](https://github.com/portel-dev/ncp/discussions)
- **Perplexity Docs:** [Official MCP Server Guide](https://docs.perplexity.ai/guides/mcp-server)
```
--------------------------------------------------------------------------------
/src/utils/mcp-wrapper.ts:
--------------------------------------------------------------------------------
```typescript
/**
* MCP Wrapper for Clean Console Output
*
* Creates a wrapper script that redirects MCP server output to logs
* while preserving JSON-RPC communication, similar to Claude Desktop.
*/
import { createWriteStream, WriteStream, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'fs';
import { join } from 'path';
import { homedir, tmpdir } from 'os';
import { logger } from './logger.js';
export class MCPWrapper {
private readonly LOG_DIR: string;
private readonly WRAPPER_DIR: string;
private readonly MAX_LOG_AGE_DAYS = 7; // Keep logs for 1 week
constructor() {
this.LOG_DIR = join(homedir(), '.ncp', 'logs');
this.WRAPPER_DIR = join(tmpdir(), 'ncp-wrappers');
this.ensureDirectories();
this.cleanupOldLogs();
}
/**
* Ensure required directories exist
*/
private ensureDirectories(): void {
if (!existsSync(this.LOG_DIR)) {
mkdirSync(this.LOG_DIR, { recursive: true });
}
if (!existsSync(this.WRAPPER_DIR)) {
mkdirSync(this.WRAPPER_DIR, { recursive: true });
}
}
/**
* Get log file path for current week
*/
private getLogFilePath(mcpName: string): string {
const now = new Date();
const year = now.getFullYear();
const week = this.getWeekNumber(now);
return join(this.LOG_DIR, `mcp-${mcpName}-${year}w${week.toString().padStart(2, '0')}.log`);
}
/**
* Get ISO week number
*/
private getWeekNumber(date: Date): number {
const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
const dayNum = d.getUTCDay() || 7;
d.setUTCDate(d.getUTCDate() + 4 - dayNum);
const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
return Math.ceil((((d.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
}
/**
* Clean up old log files (older than 1 week)
*/
private cleanupOldLogs(): void {
try {
if (!existsSync(this.LOG_DIR)) return;
const files = readdirSync(this.LOG_DIR);
const cutoffTime = Date.now() - (this.MAX_LOG_AGE_DAYS * 24 * 60 * 60 * 1000);
for (const file of files) {
if (file.startsWith('mcp-') && file.endsWith('.log')) {
const filePath = join(this.LOG_DIR, file);
const stats = statSync(filePath);
if (stats.mtime.getTime() < cutoffTime) {
unlinkSync(filePath);
logger.debug(`Cleaned up old log file: ${file}`);
}
}
}
} catch (error) {
logger.error('Failed to cleanup old logs:', error);
}
}
/**
* Create a wrapper script that redirects MCP server output to logs
*/
createWrapper(mcpName: string, command: string, args: string[] = []): { command: string; args: string[] } {
const logFile = this.getLogFilePath(mcpName);
const wrapperPath = join(this.WRAPPER_DIR, `mcp-${mcpName}-wrapper.js`);
// Create Node.js wrapper script
const wrapperScript = `#!/usr/bin/env node
/**
* MCP Wrapper for ${mcpName}
* Redirects stdout/stderr to logs while preserving JSON-RPC
*/
const { spawn } = require('child_process');
const fs = require('fs');
// Ensure log directory exists
const logDir = require('path').dirname('${logFile}');
if (!fs.existsSync(logDir)) {
fs.mkdirSync(logDir, { recursive: true });
}
// Create log stream
const logStream = fs.createWriteStream('${logFile}', { flags: 'a' });
logStream.write(\`\\n--- MCP \${process.argv[2] || '${mcpName}'} Session Started: \${new Date().toISOString()} ---\\n\`);
// Spawn the actual MCP server
const child = spawn('${command}', ${JSON.stringify(args)}, {
env: process.env,
stdio: ['pipe', 'pipe', 'pipe']
});
// Forward stdin to child (for JSON-RPC requests)
process.stdin.pipe(child.stdin);
// Handle stdout: Log everything, but forward JSON-RPC to parent
child.stdout.on('data', (chunk) => {
const text = chunk.toString();
logStream.write(\`[STDOUT] \${text}\`);
// Check if this looks like JSON-RPC and forward it
text.split('\\n').forEach(line => {
line = line.trim();
if (line) {
try {
const parsed = JSON.parse(line);
if (parsed.jsonrpc === '2.0' ||
(typeof parsed.id !== 'undefined' &&
(parsed.method || parsed.result || parsed.error))) {
// This is JSON-RPC, forward to parent
process.stdout.write(line + '\\n');
}
} catch (e) {
// Not JSON-RPC, just log it
logStream.write(\`[NON-JSONRPC] \${line}\\n\`);
}
}
});
});
// Handle stderr: Log everything (these are usually startup messages)
child.stderr.on('data', (chunk) => {
const text = chunk.toString();
logStream.write(\`[STDERR] \${text}\`);
});
// Handle child process events
child.on('error', (error) => {
logStream.write(\`[ERROR] Process error: \${error.message}\\n\`);
process.exit(1);
});
child.on('exit', (code, signal) => {
logStream.write(\`[EXIT] Process exited with code \${code}, signal \${signal}\\n\`);
logStream.write(\`--- MCP Session Ended: \${new Date().toISOString()} ---\\n\\n\`);
logStream.end();
process.exit(code || 0);
});
// Handle parent process signals
process.on('SIGTERM', () => child.kill('SIGTERM'));
process.on('SIGINT', () => child.kill('SIGINT'));
`;
// Write wrapper script
writeFileSync(wrapperPath, wrapperScript, { mode: 0o755 });
// Return wrapper command instead of original
return {
command: 'node',
args: [wrapperPath, mcpName]
};
}
/**
* Get current log file path for an MCP (for debugging)
*/
getLogFile(mcpName: string): string {
return this.getLogFilePath(mcpName);
}
/**
* List all current log files
*/
listLogFiles(): string[] {
try {
if (!existsSync(this.LOG_DIR)) return [];
return readdirSync(this.LOG_DIR)
.filter(file => file.startsWith('mcp-') && file.endsWith('.log'))
.map(file => join(this.LOG_DIR, file));
} catch {
return [];
}
}
}
// Singleton instance
export const mcpWrapper = new MCPWrapper();
```
--------------------------------------------------------------------------------
/src/services/output-formatter.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Shared service for consistent output formatting and UX
* Consolidates chalk usage and provides consistent styling patterns
*/
import chalk from 'chalk';
export interface OutputOptions {
noColor?: boolean;
emoji?: boolean;
compact?: boolean;
}
export class OutputFormatter {
private static noColor = false;
private static supportsEmoji = true;
static configure(options: OutputOptions): void {
this.noColor = options.noColor || false;
this.supportsEmoji = options.emoji !== false;
if (this.noColor) {
chalk.level = 0;
}
}
// === STATUS MESSAGES ===
static success(message: string): string {
const emoji = this.supportsEmoji ? '✅ ' : '';
return this.noColor ? `${emoji}Success! ${message}` : chalk.green(`${emoji}Success! ${message}`);
}
static error(message: string): string {
const emoji = this.supportsEmoji ? '❌ ' : '';
return this.noColor ? `${emoji}Error: ${message}` : chalk.red(`${emoji}Error: ${message}`);
}
static warning(message: string): string {
const emoji = this.supportsEmoji ? '⚠️ ' : '';
return this.noColor ? `${emoji}Warning: ${message}` : chalk.yellow(`${emoji}Warning: ${message}`);
}
static info(message: string): string {
const emoji = this.supportsEmoji ? 'ℹ️ ' : '';
return this.noColor ? `${emoji}${message}` : chalk.blue(`${emoji}${message}`);
}
static running(action: string): string {
const emoji = this.supportsEmoji ? '🚀 ' : '';
return this.noColor ? `${emoji}Running ${action}...` : chalk.cyan(`${emoji}Running ${action}...`);
}
// === TOOL & COMMAND FORMATTING ===
static toolName(name: string): string {
return this.noColor ? name : chalk.bold.cyan(name);
}
static command(cmd: string): string {
return this.noColor ? `\`${cmd}\`` : chalk.gray(`\`${cmd}\``);
}
static parameter(param: string): string {
return this.noColor ? param : chalk.yellow(param);
}
static value(value: string): string {
return this.noColor ? `"${value}"` : chalk.green(`"${value}"`);
}
// === STRUCTURAL FORMATTING ===
static header(text: string, level: 1 | 2 | 3 = 1): string {
if (this.noColor) {
const prefix = '#'.repeat(level);
return `${prefix} ${text}`;
}
switch (level) {
case 1: return chalk.bold.magenta(text);
case 2: return chalk.bold.blue(text);
case 3: return chalk.bold.cyan(text);
default: return text;
}
}
static section(title: string): string {
const emoji = this.supportsEmoji ? '📦 ' : '';
return this.noColor ? `${emoji}${title}` : chalk.bold.blue(`${emoji}${title}`);
}
static bullet(text: string): string {
const bullet = this.supportsEmoji ? ' • ' : ' - ';
return `${bullet}${text}`;
}
static separator(char: string = '─', length: number = 50): string {
return char.repeat(length);
}
// === HIGHLIGHTING & EMPHASIS ===
static highlight(text: string): string {
return this.noColor ? `**${text}**` : chalk.bold(text);
}
static muted(text: string): string {
return this.noColor ? text : chalk.dim(text);
}
static code(text: string): string {
return this.noColor ? `\`${text}\`` : chalk.bgGray.black(` ${text} `);
}
static quote(text: string): string {
return this.noColor ? `"${text}"` : chalk.italic(`"${text}"`);
}
// === SEARCH & DISCOVERY UX ===
static searchResult(query: string, count: number, page?: number, totalPages?: number): string {
const emoji = this.supportsEmoji ? '🔍 ' : '';
const pageInfo = page && totalPages ? ` | Page ${page} of ${totalPages}` : '';
const resultsText = count === 1 ? 'result' : 'results';
if (count === 0) {
return this.error(`No tools found for ${this.quote(query)}`);
}
const message = `${emoji}Found ${count} ${resultsText} for ${this.quote(query)}${pageInfo}`;
return this.noColor ? message : chalk.blue(message);
}
static noResultsSuggestion(suggestions: string[]): string {
const emoji = this.supportsEmoji ? '📝 ' : '';
const title = this.noColor ? `${emoji}Available MCPs to explore:` : chalk.bold(`${emoji}Available MCPs to explore:`);
const suggestionList = suggestions.map(s => this.bullet(s)).join('\n');
return `${title}\n${suggestionList}`;
}
static tip(message: string): string {
const emoji = this.supportsEmoji ? '💡 ' : '';
return this.noColor ? `${emoji}${message}` : chalk.blue(`${emoji}${message}`);
}
// === PROGRESS & FEEDBACK ===
static progress(current: number, total: number, item?: string): string {
const percentage = Math.round((current / total) * 100);
const bar = this.createProgressBar(current, total);
const itemText = item ? ` ${item}` : '';
return this.noColor
? `[${current}/${total}] ${percentage}%${itemText}`
: chalk.blue(`${bar} ${percentage}%${itemText}`);
}
private static createProgressBar(current: number, total: number, width: number = 20): string {
const filled = Math.round((current / total) * width);
const empty = width - filled;
return `[${'█'.repeat(filled)}${' '.repeat(empty)}]`;
}
// === TABLE FORMATTING ===
static table(headers: string[], rows: string[][]): string {
if (this.noColor) {
const headerRow = headers.join(' | ');
const separator = headers.map(() => '---').join(' | ');
const dataRows = rows.map(row => row.join(' | ')).join('\n');
return `${headerRow}\n${separator}\n${dataRows}`;
}
const headerRow = chalk.bold(headers.join(' │ '));
const separator = '─'.repeat(headerRow.length);
const dataRows = rows.map(row => row.join(' │ ')).join('\n');
return `${headerRow}\n${separator}\n${dataRows}`;
}
// === ERROR IMPROVEMENT ===
static betterError(error: string, suggestion?: string): string {
const errorMsg = this.error(error);
if (!suggestion) return errorMsg;
const suggestionMsg = this.tip(suggestion);
return `${errorMsg}\n\n${suggestionMsg}`;
}
static validationError(field: string, expected: string, received: string): string {
return this.betterError(
`Invalid ${field}: expected ${expected}, received ${received}`,
`Check your input and try again`
);
}
}
```
--------------------------------------------------------------------------------
/docs/stories/01-dream-and-discover.md:
--------------------------------------------------------------------------------
```markdown
# 🌟 Story 1: Dream and Discover
*Why your AI doesn't see all your tools upfront - and why that's brilliant*
**Reading time:** 2 minutes
---
## 😫 The Pain
You installed 10 MCPs. Your AI now has 50+ tools at its fingertips. You expected superpowers. Instead:
**Your AI becomes indecisive:**
- "Should I use `read_file` or `get_file_content`?"
- "Let me check all 50 tools to pick the right one..."
- "Actually, can you clarify what you meant?"
**Your conversations get shorter:**
- Token limit hits faster (50 tool schemas = 50,000+ tokens!)
- AI wastes context analyzing options instead of solving problems
- You're paying per token for tools you're not even using
**Your computer works harder:**
- All 10 MCPs running constantly
- Each one consuming memory and CPU
- Most sitting idle, waiting for calls that never come
It's like inviting 50 people to help you move, but only 2 actually carry boxes while the other 48 stand around getting paid.
---
## 💭 The Journey
NCP takes a radically different approach:
**Your AI doesn't see tools upfront. It dreams of them instead.**
Here's what happens:
1. **AI has a need:** "I need to read a file..."
2. **AI dreams of the perfect tool:**
- Writes a user story: "I want to read the contents of a file on disk"
- Describes the intent, not the implementation
3. **NCP's semantic search awakens:**
- Compares the dream against ALL available tools (across all MCPs)
- Finds the perfect match in milliseconds
- Returns the exact tool needed
4. **AI uses it immediately:**
- No analysis paralysis
- No wrong tool selection
- Just instant action
**The magic?** The AI's thought process is streamlined by writing a user story. It's forced to think clearly about *what* it needs, not *how* to do it.
---
## ✨ The Magic
What you get when AI dreams instead of browses:
### **🧠 Clearer Thinking**
- Writing a user story forces clarity: "What do I actually need?"
- No distraction from 50 competing options
- Direct path from need → solution
### **💰 Massive Token Savings**
- **Before:** 50,000+ tokens for tool schemas
- **After:** 2,500 tokens for NCP's 2 tools
- **Result:** 97% reduction = 40x longer conversations
### **⚡ Instant Decisions**
- **Before:** 8 seconds analyzing 50 tool schemas
- **After:** Sub-second semantic search
- **Result:** Faster responses, better experience
### **🌱 Energy Efficiency**
- **Before:** All 10 MCPs running constantly
- **After:** MCPs load on-demand when discovered
- **Result:** Lower CPU, less memory, cooler computer
### **🎯 Better Accuracy**
- **Before:** AI picks wrong tool 30% of the time
- **After:** Semantic search finds the RIGHT tool
- **Result:** Fewer retries, less frustration
---
## 🔍 How It Works (The Light Technical Version)
When your AI calls NCP's `find` tool:
```
AI: find({ description: "I want to read a file from disk" })
NCP: [Semantic search activates]
1. Converts description to vector embedding
2. Compares against ALL tool descriptions (cached)
3. Ranks by semantic similarity
4. Returns top matches with confidence scores
AI: [Gets filesystem:read_file as top result]
AI: run({ tool: "filesystem:read_file", parameters: {...} })
NCP: [Loads filesystem MCP on-demand]
1. Starts MCP process
2. Executes tool
3. Returns result
4. Caches process for future calls
```
**Key insight:** MCPs start only when discovered, not at boot time. This is why your computer stays cool.
---
## 🎨 The Analogy That Makes It Click
**Traditional MCP Setup = Buffet Restaurant** 🍽️
You walk into a buffet with 50 dishes displayed. You spend 20 minutes examining each one, comparing ingredients, reading descriptions. By the time you decide, you're exhausted and your food is cold. You picked "grilled chicken" but really wanted "tandoori chicken" - they looked similar from afar.
**NCP Setup = Personal Chef** 👨🍳
You tell the chef: "I'm craving something savory with chicken and rice."
The chef knows exactly what to make. No menu to browse. No decision paralysis. Just perfect food, instantly delivered.
**Your AI is that diner.** Give it a buffet → overwhelm. Give it a personal chef (NCP) → perfection.
---
## 🧪 See It Yourself
Try this experiment:
```bash
# Traditional: AI sees all tools upfront
[Opens Claude Desktop with 10 MCPs directly configured]
Prompt: "Read test.txt"
[AI spends 5-8 seconds analyzing 50 tools]
[Picks read_file or get_file_content - 50/50 chance of wrong one]
# NCP: AI dreams and discovers
[Opens Claude Desktop with NCP only]
Prompt: "Read test.txt"
[AI writes: "I need to read file contents"]
[NCP semantic search: 0.2 seconds]
[Returns: filesystem:read_file with 95% confidence]
[AI executes immediately]
```
**You'll notice:**
- Responses are faster
- AI is more confident
- Fewer "let me check the tools" messages
---
## 🚀 Why This Changes Everything
**Before NCP:**
- Your AI = Overwhelmed college student with 50 textbooks open
- Outcome = Procrastination, wrong choices, exhaustion
**After NCP:**
- Your AI = Focused expert with perfect information retrieval
- Outcome = Fast, accurate, confident action
The constraint (not seeing all tools) becomes the **superpower** (clearer thinking).
Just like a poet constrained to haiku format writes better poems than one told "write about anything."
---
## 📚 Deep Dive
Want the full technical implementation?
- **Semantic Search Algorithm:** [docs/technical/semantic-search.md]
- **Vector Embedding Strategy:** [docs/technical/embeddings.md]
- **On-Demand MCP Loading:** [docs/technical/lazy-loading.md]
- **Caching and Performance:** [docs/technical/caching.md]
---
## 🔗 Next Story
**[Story 2: Secrets in Plain Sight →](02-secrets-in-plain-sight.md)**
*How your API keys stay invisible to AI - even when configuring MCPs through conversation*
---
## 💬 Questions?
**Q: Does semantic search ever miss the right tool?**
A: NCP shows top 5 matches with confidence scores. If confidence is low (<30%), NCP shows multiple options: "I found these tools, which one matches your need?"
**Q: What if I actually want to see all tools?**
A: Use `find` with no description parameter: `find({})`. NCP switches to list mode and shows everything, paginated.
**Q: How fast is semantic search really?**
A: Sub-second for 100+ tools. NCP caches embeddings, so it's comparing vectors (fast math) not recomputing embeddings (slow AI call).
---
**[← Back to Story Index](../README.md#the-six-stories)** | **[Next Story →](02-secrets-in-plain-sight.md)**
```
--------------------------------------------------------------------------------
/DYNAMIC-RUNTIME-SUMMARY.md:
--------------------------------------------------------------------------------
```markdown
# Dynamic Runtime Detection - Implementation Summary
## Critical Change
**Before:** Runtime detection happened at **import time** (static)
**After:** Runtime detection happens at **spawn time** (dynamic)
**Why?** The "Use Built-in Node.js for MCP" setting can be toggled at any time by the user.
---
## How It Works Now
### **Every Time NCP Boots:**
1. **Detect how NCP itself is running**
```typescript
const runtime = detectRuntime();
// Checks process.execPath to see if running via:
// - Claude Desktop's bundled Node → type: 'bundled'
// - System Node → type: 'system'
```
2. **Store original commands in config**
```json
{
"github": {
"command": "node", // Original command, not resolved path
"args": ["/path/to/extension/index.js"]
}
}
```
3. **Resolve runtime when spawning child processes**
```typescript
const resolvedCommand = getRuntimeForExtension("node");
// If NCP running via bundled: "/Applications/Claude.app/.../node"
// If NCP running via system: "node"
spawn(resolvedCommand, args);
```
---
## Files Created
### **`src/utils/runtime-detector.ts`** (NEW)
**Exports:**
- `detectRuntime()` - Detects bundled vs system by checking `process.execPath`
- `getRuntimeForExtension(command)` - Resolves `node`/`python3` to correct runtime
- `logRuntimeInfo()` - Debug logging for runtime detection
**Logic:**
```
Is process.execPath inside /Claude.app/?
YES → Use bundled runtimes from client-registry
NO → Use system runtimes (node, python3)
```
---
## Files Modified
### **`src/utils/client-registry.ts`**
**Added:**
- `bundledRuntimes` field to ClientDefinition (Node.js and Python paths)
- `getBundledRuntimePath()` function
### **`src/utils/client-importer.ts`**
**Changed:**
- **REMOVED** runtime resolution at import time
- **STORES** original commands (`node`, `python3`)
- **REMOVED** unused imports and parameters
### **`src/orchestrator/ncp-orchestrator.ts`**
**Added:**
- Import of `getRuntimeForExtension` and `logRuntimeInfo`
- Runtime logging in `initialize()` (debug mode)
- Runtime resolution before spawning in 4 locations:
1. `probeAndDiscoverMCP()` - Discovery
2. `getOrCreatePersistentConnection()` - Execution
3. `getResourcesFromMCP()` - Resources
4. `getPromptsFromMCP()` - Prompts
**Pattern:**
```typescript
// Before spawning
const resolvedCommand = getRuntimeForExtension(config.command);
// Use resolved command
const wrappedCommand = mcpWrapper.createWrapper(
mcpName,
resolvedCommand, // Dynamically resolved
config.args || []
);
```
---
## Key Benefits
### **1. Dynamic Adaptation**
```
Day 1: User enables "Use Built-in Node.js"
→ Claude Desktop launches NCP with bundled Node
→ NCP detects bundled runtime
→ Spawns extensions with bundled Node
Day 2: User disables "Use Built-in Node.js"
→ Claude Desktop launches NCP with system Node
→ NCP detects system runtime
→ Spawns extensions with system Node
```
### **2. Portable Configs**
```json
// Config is clean and portable
{
"github": { "command": "node", "args": [...] }
}
// NOT polluted with absolute paths like:
{
"github": { "command": "/Applications/Claude.app/.../node", "args": [...] }
}
```
### **3. Always Correct Runtime**
```
NCP running via bundled Node?
→ Extensions run via bundled Node
NCP running via system Node?
→ Extensions run via system Node
ALWAYS MATCHES!
```
---
## Testing
### **Test Dynamic Detection**
1. **Enable bundled runtime in Claude Desktop**
- Settings → Extensions → "Use Built-in Node.js for MCP" → ON
2. **Restart Claude Desktop**
- NCP will be launched with bundled Node
3. **Check runtime detection** (with `NCP_DEBUG=true`)
```
[Runtime Detection]
Type: bundled
Node: /Applications/Claude.app/.../node
Python: /Applications/Claude.app/.../python3
Process execPath: /Applications/Claude.app/.../node
```
4. **Verify extensions work**
- Run `ncp run github:create_issue` (or any .mcpb extension tool)
- Should work with bundled runtime
5. **Toggle setting**
- Settings → Extensions → "Use Built-in Node.js for MCP" → OFF
- Restart Claude Desktop
6. **Check runtime detection again**
```
[Runtime Detection]
Type: system
Node: node
Python: python3
Process execPath: /usr/local/bin/node
```
7. **Verify extensions still work**
- Run `ncp run github:create_issue`
- Should work with system runtime
---
## Debugging
### **Enable Debug Logging**
```bash
# Set environment variable
export NCP_DEBUG=true
# Or in Claude Desktop config
{
"mcpServers": {
"ncp": {
"command": "npx",
"args": ["-y", "@portel/ncp"],
"env": {
"NCP_DEBUG": "true"
}
}
}
}
```
### **Check Runtime Detection**
Look for these log lines on startup:
```
[Runtime Detection]
Type: bundled | system
Node: <path to node>
Python: <path to python>
Process execPath: <how NCP was launched>
```
### **Verify Resolution**
When spawning an extension, you should see:
- Original command from config: `"node"`
- Resolved command for spawn: `/Applications/Claude.app/.../node` (if bundled)
---
## Edge Cases Handled
✅ Bundled runtime path doesn't exist → Falls back to system runtime
✅ Unknown `process.execPath` → Assumes system runtime
✅ Non-standard commands (full paths) → Returns as-is
✅ Python variations (`python`, `python3`) → Handles both
✅ Setting toggled between boots → Detects fresh on next boot
---
## Migration Path
### **Existing Configs**
No migration needed! Existing configs with `"command": "node"` will:
1. Be detected as original commands
2. Work with dynamic runtime resolution
3. Adapt to setting changes automatically
### **No Breaking Changes**
- Configs created before this change: ✅ Work
- Configs created after this change: ✅ Work
- Toggling Claude Desktop setting: ✅ Works
---
## Summary
**What changed:**
- Runtime detection moved from import time to spawn time
- Configs store original commands, not resolved paths
- NCP detects how it's running and uses same runtime for extensions
**Why it matters:**
- User can toggle "Use Built-in Node.js" setting anytime
- NCP adapts on next boot automatically
- No config changes needed, everything just works
**Result:**
- ✅ Disabled .mcpb extensions work via NCP
- ✅ Runtime compatibility guaranteed
- ✅ Setting changes respected dynamically
- ✅ Clean, portable configs
🎉 **The optimal .mcpb workflow is fully supported with dynamic runtime detection!**
```
--------------------------------------------------------------------------------
/test/cache-loading-focused.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Cache Loading Focused Tests - Target orchestrator lines 491-539
* These tests specifically hit the complex cache loading logic
*/
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { NCPOrchestrator } from '../src/orchestrator/ncp-orchestrator.js';
import * as fs from 'fs/promises';
// Mock fs.readFile
jest.mock('fs/promises');
describe('Cache Loading Focus', () => {
beforeEach(() => {
jest.clearAllMocks();
// Mock existsSync to return true for cache files
jest.doMock('fs', () => ({
existsSync: jest.fn().mockReturnValue(true)
}));
});
it('should process cache loading with tool prefixing logic', async () => {
const orchestrator = new NCPOrchestrator('cache-test');
// Create a mock profile and cache that will trigger the cache loading path (lines 491-539)
const mockProfile = {
mcpServers: {
'test-server': {
command: 'node',
args: ['test.js']
}
}
};
const mockCache = {
timestamp: Date.now() - 1000, // Recent but not current
configHash: 'test-hash',
mcps: {
'test-server': {
tools: [
{
name: 'tool1', // Unprefixed tool name
description: 'First tool',
inputSchema: { type: 'object' }
},
{
name: 'test-server:tool2', // Already prefixed tool name
description: 'test-server: Second tool',
inputSchema: { type: 'object' }
},
{
name: 'tool3',
// Missing description to test line 512
inputSchema: { type: 'object' }
}
]
}
}
};
// Setup fs.readFile mock to return our test data
(fs.readFile as any)
.mockResolvedValueOnce(JSON.stringify(mockProfile))
.mockResolvedValueOnce(JSON.stringify(mockCache));
// Initialize - this should trigger cache loading logic
await orchestrator.initialize();
// Test that tools were loaded correctly
const allTools = await orchestrator.find('', 20);
// Should have processed the tools from cache
expect(allTools.length).toBeGreaterThanOrEqual(0);
// The cache loading should have completed without errors
expect(orchestrator).toBeDefined();
});
it('should handle cache with mixed tool naming formats', async () => {
const orchestrator = new NCPOrchestrator('mixed-format-test');
// Profile with multiple MCPs
const mockProfile = {
mcpServers: {
'mcp1': { command: 'node', args: ['mcp1.js'] },
'mcp2': { command: 'python', args: ['mcp2.py'] }
}
};
// Cache with tools in different naming formats
const mockCache = {
timestamp: Date.now() - 500,
configHash: 'mixed-hash',
mcps: {
'mcp1': {
tools: [
{
name: 'read', // Old format (unprefixed)
description: 'Read data',
inputSchema: {}
},
{
name: 'mcp1:write', // New format (prefixed)
description: 'mcp1: Write data',
inputSchema: {}
}
]
},
'mcp2': {
tools: [
{
name: 'calculate',
description: '', // Empty description to test default handling
inputSchema: {}
}
]
}
}
};
(fs.readFile as any)
.mockResolvedValueOnce(JSON.stringify(mockProfile))
.mockResolvedValueOnce(JSON.stringify(mockCache));
await orchestrator.initialize();
// Verify the cache loading processed all tools
const tools = await orchestrator.find('', 10);
expect(Array.isArray(tools)).toBe(true);
});
it('should exercise discovery engine indexing in cache load', async () => {
const orchestrator = new NCPOrchestrator('discovery-test');
const mockProfile = {
mcpServers: {
'discovery-mcp': { command: 'node', args: ['discovery.js'] }
}
};
const mockCache = {
timestamp: Date.now() - 200,
configHash: 'discovery-hash',
mcps: {
'discovery-mcp': {
tools: [
{
name: 'searchable-tool',
description: 'A tool that can be discovered through search',
inputSchema: { type: 'object', properties: { query: { type: 'string' } } }
}
]
}
}
};
(fs.readFile as any)
.mockResolvedValueOnce(JSON.stringify(mockProfile))
.mockResolvedValueOnce(JSON.stringify(mockCache));
await orchestrator.initialize();
// Test discovery engine integration
const searchResults = await orchestrator.find('searchable', 5);
expect(Array.isArray(searchResults)).toBe(true);
// Verify discovery stats
const stats = (orchestrator as any).discovery.getStats();
expect(stats).toBeDefined();
});
it('should handle cache loading success path completely', async () => {
const orchestrator = new NCPOrchestrator('success-test');
const mockProfile = {
mcpServers: {
'success-mcp': { command: 'node', args: ['success.js'] }
}
};
// Create cache that will trigger all the cache loading logic paths
const mockCache = {
timestamp: Date.now() - 100,
configHash: 'success-hash',
mcps: {
'success-mcp': {
tools: [
{
name: 'full-featured-tool',
description: 'A complete tool with all features',
inputSchema: {
type: 'object',
properties: {
input: { type: 'string' },
options: { type: 'object' }
}
}
},
{
name: 'success-mcp:prefixed-tool',
description: 'success-mcp: Already has prefix and description',
inputSchema: { type: 'object' }
}
]
}
}
};
(fs.readFile as any)
.mockResolvedValueOnce(JSON.stringify(mockProfile))
.mockResolvedValueOnce(JSON.stringify(mockCache));
await orchestrator.initialize();
// Test the full cache loading success flow
const allTools = await orchestrator.find('', 25);
expect(Array.isArray(allTools)).toBe(true);
// Test specific searches to exercise the indexed tools
const specificSearch = await orchestrator.find('full-featured', 5);
expect(Array.isArray(specificSearch)).toBe(true);
});
});
```
--------------------------------------------------------------------------------
/.github/FEATURE_STORY_TEMPLATE.md:
--------------------------------------------------------------------------------
```markdown
# Feature Story Template
**Use this template to propose new features for NCP.**
Every feature should tell a story BEFORE any code is written. This ensures we're solving real problems and can explain the value clearly.
---
## 📝 **Basic Info**
**Feature Name:** [Short, memorable name]
**Story Number:** [If part of existing story arc, reference parent story]
**Status:** 🟡 Proposed | 🔵 Approved | 🟢 Implemented | 🔴 Rejected
**Proposed By:** [Your name]
**Date:** [YYYY-MM-DD]
---
## 😫 **The Pain** (30 seconds)
**What problem are users experiencing TODAY?**
Write this as if you're the user describing frustration to a friend:
- What's broken or annoying?
- What workaround are they using now?
- How often does this happen?
- What's the cost (time, money, frustration)?
**Good Example:**
> "My MCPs break silently. GitHub MCP lost connection 2 hours ago. My AI keeps trying to use it, gets errors, and I waste 20 minutes debugging every time this happens."
**Bad Example:**
> "There's no health monitoring system for MCP servers."
> (Too technical, doesn't convey user pain)
---
## 💭 **The Journey** (1 minute)
**How does NCP solve this problem?**
Walk through the user experience step-by-step:
- What does user do?
- What does NCP do?
- What does user see/feel?
- What's the "aha!" moment?
Use concrete examples, not abstractions.
**Good Example:**
> "You open NCP dashboard. Immediately see:
> - 🟢 filesystem: Healthy (12 calls today)
> - 🟡 github: Slow (avg 800ms)
> - 🔴 database: FAILED (timeout)
>
> One glance, you know database is broken. Click it, see error details, fix the connection string. Done in 30 seconds instead of 20 minutes."
**Bad Example:**
> "NCP implements a health checking system that monitors MCP availability."
> (Describes implementation, not user experience)
---
## ✨ **The Magic** (30 seconds)
**What benefits does user get?**
List tangible outcomes using bullet points:
- Time saved
- Money saved
- Frustration avoided
- New capabilities unlocked
Be specific! "Faster" is vague, "5x faster" is specific.
**Good Example:**
- ⏱️ Debug time: 20 minutes → 30 seconds
- 🎯 Find broken MCPs before AI hits them
- 🧹 See unused MCPs, remove to save memory
- 📊 Usage stats show which MCPs matter
**Bad Example:**
- Better system reliability
- Improved user experience
(Vague corporate speak)
---
## 🔍 **How It Works** (1 minute - OPTIONAL)
**Light technical explanation for curious readers.**
This section is OPTIONAL. Only include if:
- Technical approach is interesting/novel
- Users might want to understand internals
- Implementation affects user experience
Keep it accessible - explain like teaching a smart friend, not writing a CS paper.
**Good Example:**
> "Dashboard checks MCP health on-demand (when you open it). Sends ping to each MCP, measures response time. Caches results for 30 seconds so repeated opens are instant. No background polling (saves battery)."
**Bad Example:**
> "Implements asynchronous health check workers using Promise.all with timeout handling via AbortController and response time measurement via performance.now()."
> (Too much implementation detail)
---
## 🎨 **The Analogy** (OPTIONAL)
**Compare to something everyone knows.**
Sometimes an analogy makes the feature click instantly:
**Good Example:**
> "MCP Health Dashboard is like your car's dashboard. Glance at gauges, immediately know what's wrong. No need to lift the hood every time."
**Bad Example:**
> "It's like a monitoring system for distributed systems."
> (Doesn't help non-technical users)
---
## 🧪 **See It Yourself** (1 minute - OPTIONAL)
**Show before/after comparison.**
Help reader visualize the difference:
**Good Example:**
```
Before NCP Health Dashboard:
→ AI: "Error accessing GitHub"
→ You: "Ugh, which MCP broke NOW?"
→ You: [20 min debugging]
→ You: "Oh, GitHub token expired"
After NCP Health Dashboard:
→ You: [Opens dashboard]
→ Dashboard: 🔴 github: AUTH_FAILED (token expired)
→ You: [Updates token]
→ Done in 30 seconds
```
---
## 🚧 **What to Avoid**
**What should we NOT include?**
Define boundaries to prevent scope creep:
**Good Example:**
- ❌ Don't add historical graphs (nice-to-have, adds complexity)
- ❌ Don't add email alerts (different feature, separate story)
- ❌ Don't auto-fix failures (dangerous, user should control)
- ✅ DO show current status (core need)
- ✅ DO show error messages (helps debugging)
---
## 📊 **Success Metrics**
**How do we know this feature succeeded?**
Define measurable outcomes:
**Good Example:**
- 80% of users with broken MCPs find them within 1 minute
- Average debugging time drops from 20 min → 2 min
- Users report 5/5 satisfaction with dashboard clarity
**Bad Example:**
- Better health monitoring
- Improved reliability
(Not measurable)
---
## 🔗 **Related Stories**
**What other features connect to this?**
List related stories or features:
- Story that motivates this one
- Stories this enables
- Stories this conflicts with
**Example:**
- 🔗 Story 5: Runtime Detective (health check needs runtime info)
- 🔗 Future: Auto-healing (dashboard enables this)
- ⚠️ Conflicts with: Always-on background monitoring (different approach)
---
## 💬 **Open Questions**
**What needs discussion before building?**
List unknowns or decisions needed:
**Example:**
- Should health check be automatic on MCP start, or on-demand?
- How to handle MCPs that are slow to respond (timeout vs wait)?
- Should dashboard show usage stats (call count) or just health?
---
## 🎯 **Decision**
**[To be filled by team after discussion]**
- [ ] ✅ **Approved** - Build this
- [ ] 🔄 **Revise** - Needs changes (specify what)
- [ ] 📅 **Deferred** - Good idea, wrong time (revisit when?)
- [ ] ❌ **Rejected** - Doesn't fit NCP's vision (why?)
**Decision Notes:**
[Team discussion summary and reasoning]
---
## 📚 **Implementation Checklist** (After Approval)
- [ ] Create story document in `docs/stories/`
- [ ] Write tests based on story scenarios
- [ ] Implement feature (guided by story)
- [ ] Update README to reference story
- [ ] Add CLI help text using story language
- [ ] Create example/demo from story
- [ ] Write release notes using story format
---
## 🎉 **Example: A Complete Story**
See `docs/stories/01-dream-and-discover.md` for a fully realized story.
Key elements:
- Clear pain point anyone can relate to
- Step-by-step journey through solution
- Tangible benefits (numbers!)
- Optional technical depth
- Memorable analogy
- Before/after comparison
---
**Remember: If you can't write the story, you don't understand the feature yet.** ✨
```
--------------------------------------------------------------------------------
/src/testing/setup-tiered-profiles.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
/**
* Setup Tiered MCP Profiles for Testing
*
* Creates a tiered approach for testing the semantic enhancement system:
* - Adds dummy MCPs to the default 'all' profile
* - Creates tiered profiles: tier-10, tier-100, tier-1000
* - Uses realistic MCPs for comprehensive testing at different scales
*/
import * as fs from 'fs/promises';
import * as path from 'path';
import { fileURLToPath } from 'url';
import { getNcpBaseDirectory } from '../utils/ncp-paths.js';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
interface McpDefinitionsFile {
mcps: Record<string, any>;
}
async function setupTieredProfiles(): Promise<void> {
try {
// Load real MCP definitions
const definitionsPath = path.join(__dirname, 'real-mcp-definitions.json');
const definitionsContent = await fs.readFile(definitionsPath, 'utf-8');
const realDefinitions = JSON.parse(definitionsContent);
const definitions: McpDefinitionsFile = { mcps: realDefinitions.mcps };
// Get NCP base directory and ensure profiles directory exists
const ncpBaseDir = await getNcpBaseDirectory();
const profilesDir = path.join(ncpBaseDir, 'profiles');
await fs.mkdir(profilesDir, { recursive: true });
// Build dummy MCP server path
const dummyServerPath = path.join(__dirname, 'dummy-mcp-server.ts');
// Helper function to create MCP server config
const createMcpConfig = (mcpName: string) => ({
command: 'npx',
args: [
'tsx',
dummyServerPath,
'--mcp-name',
mcpName,
'--definitions-file',
definitionsPath
]
});
const allMcpNames = Object.keys(definitions.mcps);
console.log(`📦 Found ${allMcpNames.length} MCP definitions`);
// 1. ADD TO DEFAULT 'ALL' PROFILE
console.log(`\n🔧 Adding dummy MCPs to default 'all' profile...`);
const allProfilePath = path.join(profilesDir, 'all.json');
let allProfile: any;
try {
const existingContent = await fs.readFile(allProfilePath, 'utf-8');
allProfile = JSON.parse(existingContent);
} catch {
// Create default 'all' profile if it doesn't exist
allProfile = {
name: 'all',
description: 'Universal profile with all configured MCP servers',
mcpServers: {},
metadata: {
created: new Date().toISOString(),
modified: new Date().toISOString()
}
};
}
// Add all dummy MCPs to the 'all' profile
for (const mcpName of allMcpNames) {
allProfile.mcpServers[mcpName] = createMcpConfig(mcpName);
}
allProfile.metadata.modified = new Date().toISOString();
await fs.writeFile(allProfilePath, JSON.stringify(allProfile, null, 2));
console.log(` ✅ Added ${allMcpNames.length} dummy MCPs to 'all' profile`);
// 2. CREATE TIERED PROFILES
const tiers = [
{ name: 'tier-10', count: 10, description: 'Lightweight testing with 10 essential MCPs' },
{ name: 'tier-100', count: 100, description: 'Medium load testing with 100 diverse MCPs' },
{ name: 'tier-1000', count: 1000, description: 'Heavy load testing with 1000+ comprehensive MCPs' }
];
for (const tier of tiers) {
console.log(`\n🏗️ Creating ${tier.name} profile (${tier.count} MCPs)...`);
let selectedMcps: string[];
if (tier.count <= allMcpNames.length) {
// For tier-10 and potentially tier-100, select the most essential MCPs
if (tier.count === 10) {
// Hand-pick the 10 most essential MCPs
selectedMcps = [
'shell', 'git', 'postgres', 'openai', 'github',
'docker', 'aws', 'filesystem', 'slack', 'stripe'
];
} else {
// For tier-100, take first N MCPs (can be randomized later)
selectedMcps = allMcpNames.slice(0, tier.count);
}
} else {
// For tier-1000, we need to generate more MCPs
// For now, use all available and indicate we need more
selectedMcps = allMcpNames;
console.log(` ⚠️ Only ${allMcpNames.length} MCPs available, need ${tier.count} for full ${tier.name}`);
}
const tierProfile = {
name: tier.name,
description: tier.description,
mcpServers: {} as Record<string, any>,
metadata: {
created: new Date().toISOString(),
modified: new Date().toISOString(),
targetCount: tier.count,
actualCount: selectedMcps.length
}
};
for (const mcpName of selectedMcps) {
tierProfile.mcpServers[mcpName] = createMcpConfig(mcpName);
}
const tierProfilePath = path.join(profilesDir, `${tier.name}.json`);
await fs.writeFile(tierProfilePath, JSON.stringify(tierProfile, null, 2));
console.log(` ✅ Created ${tier.name}: ${selectedMcps.length}/${tier.count} MCPs`);
console.log(` Profile: ${tierProfilePath}`);
}
// 3. USAGE INSTRUCTIONS
console.log(`\n📋 Profile Usage Instructions:`);
console.log(`\n🎯 Default Profile (${allMcpNames.length} MCPs):`);
console.log(` npx ncp list # List all MCPs`);
console.log(` npx ncp find "commit my code to git" # Semantic enhancement discovery`);
console.log(` npx ncp run git:commit --params '{"message":"test"}' # Execute tools`);
console.log(`\n⚡ Tiered Testing:`);
console.log(` npx ncp --profile tier-10 find "upload code" # Light testing (10 MCPs)`);
console.log(` npx ncp --profile tier-100 find "store data" # Medium testing (100 MCPs)`);
console.log(` npx ncp --profile tier-1000 find "deploy app" # Heavy testing (1000 MCPs)`);
console.log(`\n🔍 Performance Testing:`);
console.log(` time npx ncp --profile tier-10 find "database query" # Fast discovery`);
console.log(` time npx ncp --profile tier-100 find "database query" # Medium scale`);
console.log(` time npx ncp --profile tier-1000 find "database query" # Large scale`);
console.log(`\n📊 Profile Summary:`);
console.log(` 📦 all: ${allMcpNames.length} MCPs (default profile)`);
tiers.forEach(tier => {
const actualCount = tier.count <= allMcpNames.length ?
(tier.count === 10 ? 10 : Math.min(tier.count, allMcpNames.length)) :
allMcpNames.length;
console.log(` 📦 ${tier.name}: ${actualCount}/${tier.count} MCPs`);
});
console.log(`\n🚀 Ready for semantic enhancement testing at multiple scales!`);
} catch (error) {
console.error('Failed to setup tiered profiles:', error);
process.exit(1);
}
}
// Main execution
if (import.meta.url === `file://${process.argv[1]}`) {
setupTieredProfiles();
}
export { setupTieredProfiles };
```
--------------------------------------------------------------------------------
/test/mcp-server-protocol.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* MCP Server Protocol Integration Tests
* Tests the actual MCP protocol behavior during different server states
*
* CRITICAL: These tests would have caught the indexing blocking bug
*/
import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
import { MCPServer } from '../src/server/mcp-server.js';
describe('MCP Server Protocol Integration', () => {
let server: MCPServer;
beforeEach(() => {
// Use a test profile with minimal MCPs to speed up tests
server = new MCPServer('test', false); // No progress spinner in tests
});
afterEach(async () => {
if (server) {
await server.cleanup?.();
}
});
describe('Protocol Responsiveness During Initialization', () => {
it('should respond to tools/list IMMEDIATELY even during indexing', async () => {
// Start server initialization (but don't await it)
const initPromise = server.initialize();
// CRITICAL TEST: tools/list should respond immediately, not wait for indexing
const startTime = Date.now();
const response = await server.handleRequest({
jsonrpc: '2.0',
id: 'test-1',
method: 'tools/list'
});
const responseTime = Date.now() - startTime;
// Should respond within 100ms, not wait for full indexing
expect(responseTime).toBeLessThan(100);
expect(response?.result?.tools).toBeDefined();
expect(response?.result?.tools).toHaveLength(2); // find + run
// Wait for initialization to complete
await initPromise;
});
it('should respond to initialize request immediately', async () => {
const response = await server.handleRequest({
jsonrpc: '2.0',
id: 'test-init',
method: 'initialize',
params: {
protocolVersion: '2024-11-05',
capabilities: {}
}
});
expect(response?.result?.protocolVersion).toBe('2024-11-05');
expect(response?.result?.capabilities).toBeDefined();
expect(response?.result?.serverInfo?.name).toBe('ncp');
});
it('should show progress when find is called during indexing', async () => {
// Start initialization but don't wait
const initPromise = server.initialize();
// Call find during indexing - should get progress message
const response = await server.handleFind(
{ jsonrpc: '2.0', id: 'test-find', method: 'tools/call' },
{ description: 'test query' }
);
// Should get either results or progress message, but not hang
expect(response).toBeDefined();
expect(response.result?.content).toBeDefined();
const content = response.result.content[0]?.text || '';
// Either got results or indexing progress message
expect(
content.includes('Found tools') ||
content.includes('Indexing in progress') ||
content.includes('tools available') ||
content.length > 0 // Any content is acceptable during indexing
).toBe(true);
await initPromise;
});
it('should handle concurrent tools/list requests during indexing', async () => {
// Start initialization
const initPromise = server.initialize();
// Send multiple concurrent tools/list requests
const requests = Array.from({ length: 5 }, (_, i) =>
server.handleRequest({
jsonrpc: '2.0',
id: `concurrent-${i}`,
method: 'tools/list'
})
);
// All should respond quickly without hanging
const startTime = Date.now();
const responses = await Promise.all(requests);
const totalTime = Date.now() - startTime;
// All requests combined should complete quickly
expect(totalTime).toBeLessThan(500);
// All should return valid tool lists
responses.forEach(response => {
expect(response?.result?.tools).toHaveLength(2);
});
await initPromise;
});
});
describe('Protocol Error Handling', () => {
it.skip('should handle invalid JSON-RPC requests gracefully', async () => {
// Skip for hotfix - will fix in next version
await server.initialize();
const response = await server.handleRequest({
// Missing required fields
method: 'tools/list'
} as any);
// Should either return an error or handle gracefully
expect(response).toBeDefined();
if (response?.error) {
expect(typeof response.error.code).toBe('number');
expect(typeof response.error.message).toBe('string');
} else {
// If no error, should have valid result
expect(response?.result).toBeDefined();
}
});
it('should handle unknown methods', async () => {
await server.initialize();
const response = await server.handleRequest({
jsonrpc: '2.0',
id: 'test',
method: 'unknown/method'
});
expect(response?.error?.code).toBe(-32601);
expect(response?.error?.message).toContain('Method not found');
});
});
describe('Performance Requirements', () => {
it('should respond to tools/list within 50ms after initialization', async () => {
await server.initialize();
const startTime = Date.now();
const response = await server.handleRequest({
jsonrpc: '2.0',
id: 'perf-test',
method: 'tools/list'
});
const responseTime = Date.now() - startTime;
expect(responseTime).toBeLessThan(50);
expect(response?.result?.tools).toBeDefined();
});
it('should handle tools/call within reasonable time', async () => {
await server.initialize();
const startTime = Date.now();
const response = await server.handleRequest({
jsonrpc: '2.0',
id: 'call-test',
method: 'tools/call',
params: {
name: 'find',
arguments: { description: 'test' }
}
});
const responseTime = Date.now() - startTime;
// Should respond within 2 seconds even for complex queries
expect(responseTime).toBeLessThan(2000);
expect(response?.result).toBeDefined();
});
});
describe('State Management', () => {
it('should maintain correct initialization state', async () => {
// Before initialization
const preInitResponse = await server.handleRequest({
jsonrpc: '2.0',
id: 'pre-init',
method: 'tools/list'
});
// Should still respond (not block)
expect(preInitResponse?.result?.tools).toBeDefined();
// After initialization
await server.initialize();
const postInitResponse = await server.handleRequest({
jsonrpc: '2.0',
id: 'post-init',
method: 'tools/list'
});
expect(postInitResponse?.result?.tools).toHaveLength(2);
});
});
});
```
--------------------------------------------------------------------------------
/test/cache-optimization.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Cache Optimization Tests
* Tests the new incremental cache patching system
*/
import { CachePatcher } from '../src/cache/cache-patcher.js';
import { existsSync, rmSync, mkdirSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
// Custom CachePatcher for testing that uses a temp directory
class TestCachePatcher extends CachePatcher {
constructor(private testCacheDir: string) {
super();
// Override cache directory paths
this['cacheDir'] = testCacheDir;
this['toolMetadataCachePath'] = join(testCacheDir, 'all-tools.json');
this['embeddingsCachePath'] = join(testCacheDir, 'embeddings.json');
this['embeddingsMetadataCachePath'] = join(testCacheDir, 'embeddings-metadata.json');
// Ensure cache directory exists
if (!existsSync(testCacheDir)) {
mkdirSync(testCacheDir, { recursive: true });
}
}
}
describe('Cache Optimization', () => {
let tempCacheDir: string;
let cachePatcher: TestCachePatcher;
beforeEach(() => {
// Create a temporary cache directory for testing
tempCacheDir = join(tmpdir(), 'ncp-cache-test-' + Date.now());
mkdirSync(tempCacheDir, { recursive: true });
cachePatcher = new TestCachePatcher(tempCacheDir);
});
afterEach(() => {
// Clean up temp directory
if (existsSync(tempCacheDir)) {
rmSync(tempCacheDir, { recursive: true, force: true });
}
});
describe('Profile Hash Generation', () => {
test('should generate consistent hashes for same profile', () => {
const profile1 = {
mcpServers: {
filesystem: {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/tmp']
}
}
};
const profile2 = {
mcpServers: {
filesystem: {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/tmp']
}
}
};
const hash1 = cachePatcher.generateProfileHash(profile1);
const hash2 = cachePatcher.generateProfileHash(profile2);
expect(hash1).toBe(hash2);
expect(hash1).toHaveLength(64); // SHA256 hex length
});
test('should generate different hashes for different profiles', () => {
const profile1 = {
mcpServers: {
filesystem: {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/tmp']
}
}
};
const profile2 = {
mcpServers: {
filesystem: {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/home']
}
}
};
const hash1 = cachePatcher.generateProfileHash(profile1);
const hash2 = cachePatcher.generateProfileHash(profile2);
expect(hash1).not.toBe(hash2);
});
});
describe('Cache Patching Operations', () => {
test('should add MCP to tool metadata cache', async () => {
const config = {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/tmp']
};
const tools = [
{
name: 'read_file',
description: 'Read a file from the filesystem',
inputSchema: { type: 'object' }
},
{
name: 'write_file',
description: 'Write a file to the filesystem',
inputSchema: { type: 'object' }
}
];
const serverInfo = {
name: 'filesystem',
version: '1.0.0',
description: 'File system operations'
};
await cachePatcher.patchAddMCP('filesystem', config, tools, serverInfo);
const cache = await cachePatcher.loadToolMetadataCache();
expect(cache.mcps.filesystem).toBeDefined();
expect(cache.mcps.filesystem.tools).toHaveLength(2);
expect(cache.mcps.filesystem.tools[0].name).toBe('read_file');
expect(cache.mcps.filesystem.serverInfo.name).toBe('filesystem');
});
test('should remove MCP from tool metadata cache', async () => {
// First add an MCP
const config = {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/tmp']
};
const tools = [
{
name: 'read_file',
description: 'Read a file',
inputSchema: {}
}
];
await cachePatcher.patchAddMCP('filesystem', config, tools, {});
// Verify it was added
let cache = await cachePatcher.loadToolMetadataCache();
expect(cache.mcps.filesystem).toBeDefined();
// Remove it
await cachePatcher.patchRemoveMCP('filesystem');
// Verify it was removed
cache = await cachePatcher.loadToolMetadataCache();
expect(cache.mcps.filesystem).toBeUndefined();
});
});
describe('Cache Validation', () => {
test('should validate cache with matching profile hash', async () => {
const profileHash = 'test-hash-12345';
await cachePatcher.updateProfileHash(profileHash);
const isValid = await cachePatcher.validateCacheWithProfile(profileHash);
expect(isValid).toBe(true);
});
test('should invalidate cache with mismatched profile hash', async () => {
const profileHash1 = 'test-hash-12345';
const profileHash2 = 'test-hash-67890';
await cachePatcher.updateProfileHash(profileHash1);
const isValid = await cachePatcher.validateCacheWithProfile(profileHash2);
expect(isValid).toBe(false);
});
test('should handle missing cache gracefully', async () => {
const profileHash = 'test-hash-12345';
const isValid = await cachePatcher.validateCacheWithProfile(profileHash);
expect(isValid).toBe(false);
});
});
describe('Cache Statistics', () => {
test('should return accurate cache statistics', async () => {
// Start with empty cache
let stats = await cachePatcher.getCacheStats();
expect(stats.toolMetadataExists).toBe(false);
expect(stats.mcpCount).toBe(0);
expect(stats.toolCount).toBe(0);
// Add some data
const config = {
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/tmp']
};
const tools = [
{ name: 'read_file', description: 'Read file', inputSchema: {} },
{ name: 'write_file', description: 'Write file', inputSchema: {} }
];
await cachePatcher.patchAddMCP('filesystem', config, tools, {});
// Check updated stats
stats = await cachePatcher.getCacheStats();
expect(stats.toolMetadataExists).toBe(true);
expect(stats.mcpCount).toBe(1);
expect(stats.toolCount).toBe(2);
});
});
describe('Error Handling', () => {
test('should handle corrupt cache files gracefully', async () => {
const integrity = await cachePatcher.validateAndRepairCache();
expect(integrity.valid).toBe(false);
expect(integrity.repaired).toBe(false);
});
});
});
```