npm package: @osuna0102/mcp
Description: MCP server for NeuralSeek — exposes seek, run/upload/list/delete agents, streaming, and logs as MCP tools for Claude Desktop, VS Code Copilot, Cursor, and any MCP-compatible AI.
Latest version: 0.2.4

# mcpns — NeuralSeek MCP Server + TypeScript SDK

Connect any MCP-compatible AI (Claude Desktop, VS Code Copilot, Cursor …) directly to your **NeuralSeek** instance.
15 tools out of the box: seek, run agents, upload/list/delete agents, stream, inspect logs, generate NTL from a description, replay run traces, and sync workspace.

---

## MCP Server — Quick Setup

### 1. Install

```bash
npm install -g @osuna0102/mcp
```

> **No install required for VS Code / Claude Desktop** — use `npx` (see step 3) and it downloads automatically on first use.

### 2. Configure your NeuralSeek instance

Create a `.neuralseekrc.json` in your home folder (or project root, or pass env vars):

```json
{
  "instance": "Your_Instance_Name",
  "apiKey":   "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx",
  "baseUrl":  "https://stagingapi.neuralseek.com/v1"
}
```

Or set environment variables instead (preferred for CI/Docker):

```
NS_INSTANCE, NS_API_KEY, NS_BASE_URL
```

All tools work with just `instance` and `apiKey`.

### 3. Add to VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "neuralseek": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@osuna0102/mcp"]
    }
  }
}
```

> Using `npx` means **no global install needed** — works on any machine with Node.js. The package is cached after the first run.

### 4. Add to Claude Desktop

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "neuralseek": {
      "command": "npx",
      "args": ["-y", "@osuna0102/mcp"]
    }
  }
}
```

> If you prefer using the globally-installed binary directly, run `npm install -g @osuna0102/mcp` first and then use `"command": "mcpns"` instead.

Restart Claude Desktop — 14 NeuralSeek tools will appear immediately.

### 5. Docker / environment-variable-only

```bash
docker run --rm -i \
  -e NS_INSTANCE="Your_Instance_Name" \
  -e NS_API_KEY="your-api-key" \
  -e NS_BASE_URL="https://stagingapi.neuralseek.com/v1" \
  node:22-alpine sh -c "npm install -g @osuna0102/mcp && mcpns"
```

Or point the config at the Docker binary:
```json
{
  "mcpServers": {
    "neuralseek": {
      "command": "docker",
      "args": ["run","--rm","-i","-e","NS_INSTANCE=...","-e","NS_API_KEY=...","mcpns-image"]
    }
  }
}
```

---

## Available MCP Tools

| Tool | Description |
|------|-----------|
| `seek` | RAG question-answering with confidence score and optional sources |
| `run_agent` | Run a local `.ntl` agent file with params |
| `run_agent_stream` | Same via SSE streaming — better for long-running agents |
| `upload_agent` | Save a local `.ntl` to your NeuralSeek instance |
| `list_agents` | List saved agents (name + description) |
| `list_agents_full` | List all agents with full NTL source + metadata |
| `get_agent` | Fetch one agent by name with its NTL source |
| `call_agent` | Run a saved agent by name with params |
| `delete_agent` | Delete one or more agents by name |
| `get_logs` | Retrieve recent mAIstro run logs with run IDs for replay |
| `replay_run` | Replay a run by ID — full step-by-step execution trace for debugging |
| `sync_agents` | Pull all instance agents to workspace (auto-runs on startup) |
| `create_agent` | Write a new NTL agent file to `agents/custom/` |
| `generate_ntl` | Generate a NTL draft from a plain-English description via makeNTL API |
| `backup_instance` | Export full instance config to a `.nsconfig` file |

All tools require only an `apiKey`. The full NTL syntax reference is available as the `ntl://reference` MCP Resource (read-on-demand, not a tool).

---

## Agent Development Workflow

When creating, testing, fixing, or touching any agent, always follow this cycle:

1. **Find** → `list_agents` / `get_agent` — retrieve current NTL from the instance
2. **Edit** → `create_agent` — write or update the local `.ntl` file in `agents/custom/`
3. **Upload** → `upload_agent` — **save to the NeuralSeek instance** (do NOT stream raw NTL inline as a test)
4. **Run** → `call_agent` — test the saved named agent on the instance
5. **Verify** output against user requirements. If not correct → repeat from step 1.

Read the `ntl://reference` MCP Resource before writing or editing NTL — it contains all 140+ nodes, params, and examples.

---

## TypeScript SDK

The package also exports a fully-typed NeuralSeek SDK:

### Installation

```bash
npm install @osuna0102/mcp
```

### Quick Start

```typescript
import { NeuralSeekClient } from '@osuna0102/mcp';

const client = new NeuralSeekClient({
  instanceId: process.env.NEURALSEEK_INSTANCE!,
  apiKey: process.env.NEURALSEEK_API_KEY!,
});

// Ask a question
const { answer, score } = await client.seek.seek({ question: 'What is NeuralSeek?' });

// Stream a response
for await (const chunk of client.seek.seekStream({ question: 'Explain mAIstro' })) {
  process.stdout.write(chunk.answer ?? '');
}

// Run a saved agent
const result = await client.maistro.run({
  agent: 'my-agent',
  params: [{ name: 'topic', value: 'loans' }],
});

// Upload an agent
await client.maistro.saveAgent({ name: 'my-agent', desc: '...', ntl: '...' });
```

### Agent Definition (TypeScript-first, equivalent of IBM YAML agent)

```typescript
import { AgentDefinition, NeuralSeekClient } from '@osuna0102/mcp';

const agent = new AgentDefinition({
  name: 'it-support-responder',
  description: 'Generate IT support responses',
  ntl: `[send to llm model="default"]
Handle this IT ticket:
Subject: $subject, Description: $description
[/send to llm]`,
  params: [
    { name: 'subject',     required: true },
    { name: 'description', required: true },
  ],
});

const { valid, errors } = agent.validate();
await client.maistro.saveAgent(agent.toSavedAgent());
```

### Module Reference

| Module | Property | Key Methods |
|---|---|---|
| Seek | `client.seek` | `seek()`, `seekStream()`, `rateAnswer()` |
| mAIstro | `client.maistro` | `run()`, `runStream()`, `listAgents()`, `listAgentsFull()`, `saveAgent()`, `getAgent()`, `deleteAgents()` |
| Extract | `client.extract` | `extractEntities()`, `categorize()` |
| Translate | `client.translate` | `translate()`, `identify()` |
| Guardrails | `client.guardrails` | `findPII()`, `semanticScore()` |
| Analytics | `client.analytics` | `getAnalytics()`, `getLogs()` |
| Keys | `client.keys` | `healthCheck()`, `validateKey()`, `runBatchTest()` |
| Curate | `client.curate` | `listIntents()`, `createIntent()`, `importQA()`, `exportQA()` |
| Configure | `client.configure` | `getSettings()`, `updateSettings()`, `listSecrets()`, `setSecret()` |

---

## CLI

```bash
neuralseek seek ask "What is NeuralSeek?"
neuralseek agent list
neuralseek agent deploy ./my-agent.agent.json
neuralseek agent run my-agent -p topic=loans
neuralseek logs list --limit 20
neuralseek health
```

---

## Building from source

```bash
npm install
npm run build       # compile to dist/
npm run typecheck   # TypeScript check
npm test            # unit tests
npm run mcp:start   # run MCP server directly via tsx (no build)
```

---

## Security

- Never commit `.neuralseekrc.json` with real credentials. It is already in `.gitignore`.
- Use `NS_API_KEY` / `NEURALSEEK_API_KEY` environment variables in CI/CD and Docker.