<p align="center">
  <img src="https://unpkg.com/nockit-mcp@latest/nockit.svg" alt="NockIt" width="128">
</p>

# Nockit ⚡

> A lightweight, low-latency Model Context Protocol (MCP) server for seamless tool execution and context integration.

[![npm version](https://img.shields.io/npm/v/nockit-mcp.svg)](https://www.npmjs.com/package/nockit-mcp)
[![license](https://img.shields.io/github/license/codecrack-01/nockit.svg)](LICENSE)
[![node version](https://img.shields.io/node/v/nockit-mcp.svg)](https://nodejs.org)

---

## 💡 Overview

**Nockit MCP** bridges the gap between AI assistants (Claude Desktop, Cursor, Zed, etc.) and local development workflows. Built with minimal overhead, it provides fast, reliable tool execution and context bridging over standard input/output (stdio) or HTTP transport layers.

- 🚀 **Lightweight & Fast:** Zero bloat, optimized for instant startup and low-latency message relay.
- 🔌 **Plug & Play:** Seamless integration with MCP-compatible clients like Claude Desktop and Cursor.
- 🛠️ **Configurable:** Simple JSON-based environment configuration.
-    **Local & Portable:** Works offline out of the box.

---

## Installation

You can run `nockit-mcp` directly using `npx` or install it globally/locally via your favorite package manager:

### Using `npx` (Recommended)
No installation required:
```bash
npx nockit-mcp@latest
```

### Global Installation

```bash
  npm install -g nockit-mcp
# or
  pnpm add -g nockit-mcp
# or    
  yarn global add nockit-mcp
```

### Local Project Dependency
```bash
  npm install nockit-mcp
```

---

## ⚡ Quickstart

### 1. Claude Desktop Integration
Add nockit-mcp to your Claude Desktop configuration file:
- Linux: ~/.config/Claude/claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

```bash 
  JSON {
    "mcpServers": {
        "nockit": {
        "command": "npx",
        "args": [
            "-y",
            "nockit-mcp@latest"
        ],
        "env": {
            "NOCKIT_LOG_LEVEL": "info"
        }
        }
    }
  }
```
Restart Claude Desktop, and the *Nockit* tools will be available automatically.

### 2. Running Locally for Development
If you are developing or testing nockit-mcp locally:

```bash
# Clone the repository
git clone [https://github.com/username/nockit.p](https://github.com/username/nockit.p)
cd nockit

# Install dependencies
npm install

# Build the package
npm run build

# Link locally for testing
npm link
```

---

## 📲 Auto-Notify (push notifications to your phone)

nockit can push a notification to your phone ([ntfy.sh](https://ntfy.sh)) the moment an AI agent starts waiting on you (`needs_input`) or finishes a task (`completed`) — with zero manual tool calls.

```bash
# One-time setup: detects installed clients and wires everything up
npx -y nockit-mcp setup

# Check what's configured
npx -y nockit-mcp status

# Manual fallback / one-off push
npx -y nockit-mcp send --status needs_input --summary "Review the PR when you're back"
```

`nockit setup` installs:

| Client | Mechanism | Events pushed |
| ------ | --------- | ------------- |
| opencode | plugin (`~/.config/opencode/plugin/`) + global config | question tool, permission prompts |
| Claude Code | `Notification` + `Stop` hooks in `~/.claude/settings.json` | `permission_prompt`, `idle_prompt`, `agent_needs_input`, `elicitation_dialog`, task completion |
| Kimi Code | `[[hooks]]` block in `~/.kimi-code/config.toml` | `PermissionRequest`, `Stop`, `task.completed` |
| Copilot CLI | hooks file in `~/.copilot/hooks/nockit.json` | `permission_prompt`, `agent_idle`, `elicitation_dialog`, completions |
| OpenClaw | best-effort hook in `~/.openclaw/hooks/` | stop / reset (no documented idle event) |
| Antigravity | MCP server in `~/.gemini/config/mcp_config.json` | MCP tool + rules only (no public hooks API) |

Install a single client explicitly: `npx -y nockit-mcp setup --client claude --client kimi`

All hooks are **fire-and-forget** (they never block or slow the agent), rate-limited to one push per 60s per client, and idempotent — re-running `setup` never duplicates hooks.

### 📣 Delivery channels

Every notification fans out to all configured channels. `nockit setup` asks about each optional channel after the ntfy topic — paste a webhook URL (or a bot token + chat id) and you're done. All channels are optional; ntfy always works.

| Channel | What you need | Where to get it |
| ------- | ------------- | --------------- |
| ntfy.sh | a topic (auto-generated) | https://ntfy.sh |
| Discord | a webhook URL | create one in your server: Settings → Integrations → Webhooks — official docs: https://discord.com/developers/docs/resources/webhook |
| Slack | an incoming webhook URL | https://api.slack.com/messaging/webhooks |
| Telegram | bot token + chat id | create a bot with **@BotFather** for the token — https://core.telegram.org/bots — then message your bot and read the chat id from `https://api.telegram.org/bot<TOKEN>/getUpdates` (send API: https://core.telegram.org/bots/api#sendmessage) |

> **Discord / Slack webhooks are simple HTTP forwarding:** nockit just POSTs the message to your webhook URL. The URL itself is a secret — it lives in `~/.config/nockit/config.json` (and the `DISCORD_WEBHOOK` / `SLACK_WEBHOOK` env vars), so keep that file private.

You can also configure channels without the interactive setup by setting the env vars below, or by editing `~/.config/nockit/config.json` directly (`discordWebhook`, `slackWebhook`, `telegramBotToken`, `telegramChatId`).

---

## ⚙️ Configuration
`nockit-mcp` can be customized using environment variables passed during execution or configured in your MCP host client:

| Environment Variable | Type     | Default     | Description                                       |
| -------------------- | -------- | ----------- | ------------------------------------------------- |
| `NOCKIT_LOG_LEVEL`   | `string` | `info`      | Log verbosity (`debug`, `info`, `warn`, `error`)  |
| `NOCKIT_PORT`        | `number` | `3000`      | Port used when running in HTTP/SSE transport mode |
| `NOCKIT_HOST`        | `string` | `localhost` | Host interface binding for HTTP mode              |
| `NTFY_TOPIC`         | `string` | `nockit_default_alerts` | ntfy.sh topic to publish to            |
| `DISCORD_WEBHOOK`    | `string` | —           | Discord webhook URL to forward notifications to   |
| `SLACK_WEBHOOK`      | `string` | —           | Slack incoming webhook URL to forward to          |
| `TELEGRAM_BOT_TOKEN` | `string` | —           | Telegram bot token (with `TELEGRAM_CHAT_ID`)      |
| `TELEGRAM_CHAT_ID`   | `string` | —           | Telegram chat id the bot sends messages to        |


--- 

## Available Tools & Capabilities
List the primary tools or capabilities exposed by your MCP server here.

- ping: Health check tool to verify server readiness and latency.
- get_status: Returns current operational metrics and system status.

---

## Testing & Verification
Run the built-in test suite:

```bash
npm test
```
To test the MCP protocol connection locally using the official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector npx nockit-mcp
```
---

## License
Distributed under the MIT License. See LICENSE for more information.