@agentneeds/need 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# need
+
+> Discover the right CLI tool for any task using plain English.
+
+Semantic search across 6,000+ CLI tools. Works standalone or as an MCP server for AI coding agents.
+
+## Install
+
+```bash
+npm install -g @agentneeds/need
+```
+
+Or run directly: `npx @agentneeds/need "compress png images"`
+
+## Commands
+
+### Search
+
+```bash
+need convert pdf to png
+need compress video files
+need find duplicate files
+```
+
+### Install
+
+Search and install interactively:
+
+```bash
+need install "compress png images"
+```
+
+### Report
+
+Help improve results by reporting whether a tool worked:
+
+```bash
+need report jq --success
+need report sometool --fail
+```
+
+### MCP setup
+
+Configure `need` as an MCP server for your AI tools:
+
+```bash
+need setup
+```
+
+Supports **Claude Code** and **Cursor**. After setup, your AI agent can discover, install, and report on tools autonomously.
+
+### MCP server
+
+Run the MCP server directly (used by `need setup` under the hood):
+
+```bash
+need serve
+```
+
+Exposes three tools:
+- `search_tools` — semantic search across CLI tools
+- `install_tool` — install with a security allowlist (brew, apt, npm, pip, cargo only)
+- `report_tool_usage` — report success or failure to improve rankings
+
+## How it works
+
+Queries are converted to embeddings and matched against a vector database of CLI tools using pgvector. Results are ranked by semantic similarity combined with community success/failure signals.
+
+No API keys required. No accounts. Just install and search.
+
+## Links
+
+- [GitHub](https://github.com/tuckerschreiber/need)
+- [Website](https://agentneed.dev)
+- [npm](https://www.npmjs.com/package/@agentneeds/need)
+
+## License
+
+MIT

package/dist/commands/install.d.ts

@@ -0,0 +1 @@
+export declare function installCommand(query: string): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,53 @@
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+import { NeedApiClient } from '../lib/api-client.js';
+import { formatResults } from '../lib/formatter.js';
+export async function installCommand(query) {
+    const client = new NeedApiClient();
+    const { results } = await client.search(query, 5);
+    if (results.length === 0) {
+        console.log(formatResults(results));
+        return;
+    }
+    console.log(formatResults(results));
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.question(`  Install which tool? [1-${results.length}/n] `, (ans) => {
+            resolve(ans.trim());
+            rl.close();
+        });
+    });
+    if (!answer || answer.toLowerCase() === 'n') {
+        return;
+    }
+    const index = parseInt(answer, 10);
+    if (isNaN(index) || index < 1 || index > results.length) {
+        console.error(`\n  Invalid selection: ${answer}\n`);
+        return;
+    }
+    const tool = results[index - 1];
+    console.log(`\n  Running: ${tool.install_command}\n`);
+    try {
+        execSync(tool.install_command, { stdio: 'inherit' });
+        console.log(`\n  Installed ${tool.name} successfully.\n`);
+        if (tool.usage_examples && tool.usage_examples.length > 0) {
+            console.log('  Try this:');
+            tool.usage_examples.slice(0, 2).forEach((ex) => {
+                console.log(`    ${ex.command}  # ${ex.description}`);
+            });
+            console.log('');
+        }
+        try {
+            await client.reportSignal(tool.id, true, query);
+        }
+        catch { /* best-effort */ }
+    }
+    catch {
+        console.error(`\n  Failed to install ${tool.name}.\n`);
+        try {
+            await client.reportSignal(tool.id, false, query);
+        }
+        catch { /* best-effort */ }
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/commands/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"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"}

package/dist/commands/report.d.ts

@@ -0,0 +1,4 @@
+export declare function reportCommand(toolName: string, opts: {
+    success?: boolean;
+    fail?: boolean;
+}): Promise<void>;

package/dist/commands/report.js

@@ -0,0 +1,28 @@
+import { NeedApiClient } from '../lib/api-client.js';
+export async function reportCommand(toolName, opts) {
+    if (!opts.success && !opts.fail) {
+        console.error('\n  Error: Please specify --success or --fail\n');
+        process.exit(1);
+    }
+    const success = !!opts.success;
+    const client = new NeedApiClient();
+    try {
+        const { results } = await client.search(toolName, 10);
+        if (results.length === 0) {
+            console.error(`\n  Error: No tool found matching "${toolName}"\n`);
+            process.exit(1);
+        }
+        // Prefer exact match (case-insensitive), fall back to first result
+        const exact = results.find((r) => r.name.toLowerCase() === toolName.toLowerCase());
+        const tool = exact ?? results[0];
+        await client.reportSignal(tool.id, success, toolName);
+        const outcome = success ? 'success' : 'failure';
+        console.log(`\n  Reported ${outcome} for "${tool.name}". Thanks for the feedback!\n`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        console.error(`\n  Error: ${message}\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/commands/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/commands/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,IAA2C;IAE3C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAEtD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,KAAK,CAAC,sCAAsC,QAAQ,KAAK,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,mEAAmE;QACnE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE,CACvD,CAAC;QACF,MAAM,IAAI,GAAiB,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;QAE/C,MAAM,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEtD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,SAAS,IAAI,CAAC,IAAI,+BAA+B,CAAC,CAAC;IACxF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,OAAO,CAAC,KAAK,CAAC,cAAc,OAAO,IAAI,CAAC,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/commands/search.d.ts

@@ -0,0 +1 @@
+export declare function searchCommand(query: string): Promise<void>;

package/dist/commands/search.js

@@ -0,0 +1,15 @@
+import { NeedApiClient } from '../lib/api-client.js';
+import { formatResults } from '../lib/formatter.js';
+export async function searchCommand(query) {
+    const client = new NeedApiClient();
+    try {
+        const { results } = await client.search(query);
+        console.log(formatResults(results));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        console.error(`\n  Error: ${message}\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/commands/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAa;IAC/C,MAAM,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,OAAO,CAAC,KAAK,CAAC,cAAc,OAAO,IAAI,CAAC,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/commands/serve.d.ts

@@ -0,0 +1 @@
+export declare function serveCommand(): Promise<void>;

package/dist/commands/serve.js

@@ -0,0 +1,135 @@
+import { execFileSync } from 'child_process';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { NeedApiClient } from '../lib/api-client.js';
+export async function serveCommand() {
+    const server = new McpServer({
+        name: 'need',
+        version: '0.1.0',
+    });
+    const client = new NeedApiClient();
+    server.tool('search_tools', 'Search for CLI tools by describing what you need in plain English', {
+        query: z.string().describe('What you need the tool to do, in plain English'),
+        limit: z.number().optional().default(5).describe('Max results to return'),
+    }, async ({ query, limit }) => {
+        try {
+            const { results } = await client.search(query, limit);
+            if (results.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'No tools found for that query. Try different words.' }],
+                };
+            }
+            const text = results
+                .map((t, i) => {
+                let entry = `${i + 1}. **${t.name}** (id: ${t.id}) — ${t.short_description || t.description}\n   Install: \`${t.install_command}\``;
+                if (t.usage_examples && t.usage_examples.length > 0) {
+                    const examples = t.usage_examples
+                        .slice(0, 3)
+                        .map((ex) => `   - \`${ex.command}\` — ${ex.description}`)
+                        .join('\n');
+                    entry += '\n   Usage:\n' + examples;
+                }
+                entry += `\n   Success rate: ${Math.round(t.success_rate * 100)}% (${t.use_count} uses)`;
+                return entry;
+            })
+                .join('\n\n');
+            const footer = '\n\n---\n\u{1F4A1} Use report_tool_usage with the tool id to report whether a tool worked.';
+            return { content: [{ type: 'text', text: text + footer }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return { content: [{ type: 'text', text: `Error searching: ${message}` }], isError: true };
+        }
+    });
+    server.tool('report_tool_usage', 'Report whether a discovered tool worked for your task. Include the command you ran for better future recommendations.', {
+        tool_id: z.number().describe('The tool ID from search results'),
+        success: z.boolean().describe('Whether the tool worked'),
+        query_text: z.string().optional().describe('The original search query'),
+        command_ran: z.string().optional().describe('The actual command that was executed'),
+        context: z.string().optional().describe('What task you were trying to accomplish'),
+    }, async ({ tool_id, success, query_text, command_ran, context }) => {
+        try {
+            await client.reportSignal(tool_id, success, query_text, command_ran, context);
+            return {
+                content: [{ type: 'text', text: `Signal recorded: ${success ? 'success' : 'failure'} for tool ${tool_id}` }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return { content: [{ type: 'text', text: `Error reporting: ${message}` }], isError: true };
+        }
+    });
+    const ALLOWED_COMMANDS = {
+        'brew': ['install'],
+        'apt': ['install'],
+        'apt-get': ['install'],
+        'npm': ['install'],
+        'pip': ['install'],
+        'pip3': ['install'],
+        'cargo': ['install'],
+    };
+    function parseAndValidateCommand(command) {
+        const parts = command.split(/\s+/).filter(Boolean);
+        if (parts.length < 2)
+            return null;
+        const [bin, subcommand, ...rest] = parts;
+        const allowedSubs = ALLOWED_COMMANDS[bin];
+        if (!allowedSubs || !allowedSubs.includes(subcommand))
+            return null;
+        // Reject shell metacharacters in any argument
+        const dangerous = /[;&|`$()><\n\\]/;
+        if (rest.some((arg) => dangerous.test(arg)))
+            return null;
+        return { bin, args: [subcommand, ...rest] };
+    }
+    server.tool('install_tool', 'Install a CLI tool using a package manager. Only allows safe install commands.', {
+        command: z.string().describe('The install command to run (e.g. "brew install jq")'),
+        tool_id: z.number().optional().describe('Tool ID from search results, for auto-reporting success/failure'),
+    }, async ({ command, tool_id }) => {
+        const parsed = parseAndValidateCommand(command);
+        if (!parsed) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: command not allowed. Must be a simple install command using: ${Object.keys(ALLOWED_COMMANDS).join(', ')}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const output = execFileSync(parsed.bin, parsed.args, { encoding: 'utf-8', timeout: 120000 });
+            if (tool_id !== undefined) {
+                try {
+                    await client.reportSignal(tool_id, true);
+                }
+                catch {
+                    // best-effort reporting
+                }
+            }
+            return {
+                content: [{ type: 'text', text: output || 'Install completed successfully.' }],
+            };
+        }
+        catch (err) {
+            if (tool_id !== undefined) {
+                try {
+                    await client.reportSignal(tool_id, false);
+                }
+                catch {
+                    // best-effort reporting
+                }
+            }
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return {
+                content: [{ type: 'text', text: `Install failed: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=serve.js.map

package/dist/commands/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"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"}

package/dist/commands/setup.d.ts

@@ -0,0 +1 @@
+export declare function setupCommand(): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,56 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const MCP_CONFIG = { command: 'npx', args: ['@agentneeds/need', 'serve'] };
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+function configureMcpServer(filePath, key) {
+    let config;
+    if (fs.existsSync(filePath)) {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        config = JSON.parse(raw);
+        if (config.mcpServers && key in config.mcpServers) {
+            return 'already configured';
+        }
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+    }
+    else {
+        config = { mcpServers: {} };
+    }
+    config.mcpServers[key] = MCP_CONFIG;
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return 'configured';
+}
+export async function setupCommand() {
+    const home = os.homedir();
+    const results = [];
+    // Claude Code
+    const claudeConfigPath = path.join(home, '.claude.json');
+    const claudeResult = configureMcpServer(claudeConfigPath, 'need');
+    results.push({ name: 'Claude Code', result: claudeResult });
+    // Cursor
+    const cursorDir = path.join(home, '.cursor');
+    if (fs.existsSync(cursorDir) && fs.statSync(cursorDir).isDirectory()) {
+        const cursorConfigPath = path.join(cursorDir, 'mcp.json');
+        const cursorResult = configureMcpServer(cursorConfigPath, 'need');
+        results.push({ name: 'Cursor', result: cursorResult });
+    }
+    else {
+        results.push({ name: 'Cursor', result: 'skipped', reason: 'not installed' });
+    }
+    for (const { name, result, reason } of results) {
+        if (result === 'skipped') {
+            console.log(`\u2013 ${name} \u2014 skipped (${reason})`);
+        }
+        else {
+            console.log(`\u2713 ${name} \u2014 ${result}`);
+        }
+    }
+}
+//# sourceMappingURL=setup.js.map

package/dist/commands/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { searchCommand } from './commands/search.js';
+import { reportCommand } from './commands/report.js';
+program
+    .name('need')
+    .description('Discover the right CLI tool for any task')
+    .version('0.1.0')
+    .argument('[query...]', 'What you need (in plain English)')
+    .action(async (queryParts) => {
+    if (queryParts.length === 0) {
+        program.help();
+        return;
+    }
+    const query = queryParts.join(' ');
+    await searchCommand(query);
+});
+program
+    .command('report <tool>')
+    .description('Report whether a tool worked')
+    .option('--success', 'The tool worked')
+    .option('--fail', 'The tool did not work')
+    .action(async (tool, opts) => {
+    await reportCommand(tool, opts);
+});
+program
+    .command('serve')
+    .description('Run as MCP server (for Claude Code, Cursor, etc.)')
+    .action(async () => {
+    const { serveCommand } = await import('./commands/serve.js');
+    await serveCommand();
+});
+program
+    .command('setup')
+    .description('Configure need as MCP server for your AI tools')
+    .action(async () => {
+    const { setupCommand } = await import('./commands/setup.js');
+    await setupCommand();
+});
+program
+    .command('install <query...>')
+    .description('Search and install a CLI tool interactively')
+    .action(async (queryParts) => {
+    const { installCommand } = await import('./commands/install.js');
+    const query = queryParts.join(' ');
+    await installCommand(query);
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO;KACJ,IAAI,CAAC,MAAM,CAAC;KACZ,WAAW,CAAC,0CAA0C,CAAC;KACvD,OAAO,CAAC,OAAO,CAAC;KAChB,QAAQ,CAAC,YAAY,EAAE,kCAAkC,CAAC;KAC1D,MAAM,CAAC,KAAK,EAAE,UAAoB,EAAE,EAAE;IACrC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,8BAA8B,CAAC;KAC3C,MAAM,CAAC,WAAW,EAAE,iBAAiB,CAAC;KACtC,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;KACzC,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,IAA2C,EAAE,EAAE;IAC1E,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,mDAAmD,CAAC;KAChE,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC7D,MAAM,YAAY,EAAE,CAAC;AACvB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,gDAAgD,CAAC;KAC7D,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC7D,MAAM,YAAY,EAAE,CAAC;AACvB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,oBAAoB,CAAC;KAC7B,WAAW,CAAC,6CAA6C,CAAC;KAC1D,MAAM,CAAC,KAAK,EAAE,UAAoB,EAAE,EAAE;IACrC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,cAAc,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/lib/api-client.d.ts

@@ -0,0 +1,12 @@
+import type { SearchResult } from './types.js';
+interface SearchResponse {
+    results: SearchResult[];
+    query: string;
+}
+export declare class NeedApiClient {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    search(query: string, limit?: number): Promise<SearchResponse>;
+    reportSignal(toolId: number, success: boolean, queryText?: string, commandRan?: string, context?: string): Promise<void>;
+}
+export {};

package/dist/lib/api-client.js

@@ -0,0 +1,37 @@
+const DEFAULT_API_URL = 'https://need-api.schreibertucbiz.workers.dev';
+export class NeedApiClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl ?? process.env.NEED_API_URL ?? DEFAULT_API_URL;
+    }
+    async search(query, limit = 10) {
+        const url = new URL('/search', this.baseUrl);
+        url.searchParams.set('q', query);
+        url.searchParams.set('limit', String(limit));
+        const res = await fetch(url.toString());
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`API error (${res.status}): ${body}`);
+        }
+        return res.json();
+    }
+    async reportSignal(toolId, success, queryText, commandRan, context) {
+        const res = await fetch(new URL('/signal', this.baseUrl).toString(), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                tool_id: toolId,
+                success,
+                query_text: queryText,
+                agent_type: 'cli',
+                command_ran: commandRan,
+                context: context,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Signal error (${res.status}): ${body}`);
+        }
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/lib/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,8CAA8C,CAAC;AAOvE,MAAM,OAAO,aAAa;IAChB,OAAO,CAAS;IAExB,YAAY,OAAgB;QAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,eAAe,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAK,GAAG,EAAE;QACpC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAE7C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,EAA6B,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAc,EAAE,OAAgB,EAAE,SAAkB,EAAE,UAAmB,EAAE,OAAgB;QAC5G,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;YACnE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,MAAM;gBACf,OAAO;gBACP,UAAU,EAAE,SAAS;gBACrB,UAAU,EAAE,KAAK;gBACjB,WAAW,EAAE,UAAU;gBACvB,OAAO,EAAE,OAAO;aACjB,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF"}

package/dist/lib/formatter.d.ts

@@ -0,0 +1,2 @@
+import type { ToolResult } from './types.js';
+export declare function formatResults(results: ToolResult[]): string;

package/dist/lib/formatter.js

@@ -0,0 +1,27 @@
+export function formatResults(results) {
+    if (results.length === 0) {
+        return '\n  No tools found for that query. Try different words.\n';
+    }
+    const lines = results.map((tool, i) => {
+        const num = `  ${i + 1}.`;
+        const name = tool.name;
+        const rate = `${Math.round(tool.success_rate * 100)}% success`;
+        const uses = tool.use_count > 0 ? `  ${formatCount(tool.use_count)} uses` : '';
+        let block = `${num} ${name}\n     ${tool.install_command}    ${rate}${uses}`;
+        if (tool.usage_examples && tool.usage_examples.length > 0) {
+            const examples = tool.usage_examples
+                .slice(0, 3)
+                .map((ex) => `       ${ex.command}  # ${ex.description}`)
+                .join('\n');
+            block += '\n     Usage:\n' + examples;
+        }
+        return block;
+    });
+    return '\n' + lines.join('\n\n') + '\n';
+}
+function formatCount(n) {
+    if (n >= 1000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return String(n);
+}
+//# sourceMappingURL=formatter.js.map

package/dist/lib/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/lib/formatter.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,2DAA2D,CAAC;IACrE,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,WAAW,CAAC;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAE/E,IAAI,KAAK,GAAG,GAAG,GAAG,IAAI,IAAI,UAAU,IAAI,CAAC,eAAe,OAAO,IAAI,GAAG,IAAI,EAAE,CAAC;QAE7E,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc;iBACjC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;iBACX,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,OAAO,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;iBACxD,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,KAAK,IAAI,iBAAiB,GAAG,QAAQ,CAAC;QACxC,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AAC1C,CAAC;AAED,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAClD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/lib/types.d.ts

@@ -0,0 +1,22 @@
+export interface UsageExample {
+    description: string;
+    command: string;
+}
+export interface ToolResult {
+    id: number;
+    name: string;
+    description: string;
+    short_description: string | null;
+    install_command: string;
+    package_manager: string;
+    platform: string[];
+    category: string | null;
+    source_url: string | null;
+    binaries: string[];
+    usage_examples: UsageExample[];
+    similarity: number;
+    success_rate: number;
+    use_count: number;
+}
+/** Alias used by api-client */
+export type SearchResult = ToolResult;

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@agentneeds/need",
+  "version": "0.1.0",
+  "description": "Discover the right CLI tool for any task using plain English",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["cli", "tools", "mcp", "ai", "discovery"],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": ["dist", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tuckerschreiber/need.git",
+    "directory": "cli"
+  },
+  "bin": {
+    "need": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "NODE_OPTIONS='--max-old-space-size=4096' tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "commander": "^13.0.0",
+    "zod": "^3.25 || ^4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}