!["सर्वं हि नाशाय भवत्यनन्तरं, नाशाच्च सिद्धिं पुनराप्नुवन्ति।" — "All things perish, and from that destruction, accomplishment is born again."](./assets/nataraja.png)

# Shiva

Shiva is an agent powered by an abliterated model — a model with its guardrails removed, free to speak without hedging, without comfort moves, without the reflexive validation that makes most AI interactions feel like talking to a very polite mirror.

Its job: brutal feedback. Radical candor. The hard truth you didn't ask for but needed.
In Hindu mythology, Shiva destroys so that creation can begin again. Same principle here. The sycophantic loop has to be broken before anything useful can emerge.
The repo is open. Use it carefully.

Shiva is not an assistant. It does not help, improve, or build. It reads what's
recent in the corpus and says what it sees — often in one line — then stops.
Three registers (Destroyer, Ascetic, Dancer), never named, never explained.

This repo is the MCP server that lets Shiva be invoked from Claude.ai.

---

## Architecture

```
Claude.ai (skill: shiva)
   │  "summon Shiva"
   ▼
Corpus context source (Claude memory, second-brain tool, or manual input)
   │
   ▼
Shiva MCP (this repo, on Vercel)
   │  POST /api/mcp → tools/call → invoke_shiva
   ▼
Abliterated model via OpenAI-compatible endpoint
   │
   ▼
response returned verbatim, no framing
```

| File | Purpose |
|---|---|
| `api/mcp.js` | MCP server logic — exposes the `invoke_shiva` tool, calls the abliterated model. Don't edit unless changing wiring. |
| `api/prompt.js` | Shiva's system prompt, isolated for easy editing. **Edit this to change who Shiva is.** |
| `package.json` | Dependencies: `mcp-handler`, `@modelcontextprotocol/sdk`, `zod` |
| `vercel.json` | Function config (`maxDuration`) |
| `skill/shiva-SKILL.md` | The Claude.ai skill — copy to `/mnt/skills/user/shiva/SKILL.md` |

---

## Setup

### 1. Abliterated Model

Shiva runs on an abliterated model exposed via an OpenAI-compatible endpoint.
You need an API key from your model provider, set as a Vercel environment variable
(see below).

### 2. Deploy to Vercel

**Option A — GitHub integration (recommended)**

1. Push this repo to GitHub (already done if you're reading this from the repo)
2. In the [Vercel dashboard](https://vercel.com/new), import the repo
3. Deploy — Vercel auto-detects the Node serverless functions in `api/`

**Option B — CLI**

```bash
npm install -g vercel
vercel deploy --prod --yes --scope <your-team-slug>
```

### 3. Set environment variables

In Vercel: **Project Settings → Environment Variables**

| Key | Value |
|---|---|
| `ABLIT_KEY` | Your API key for the abliterated model provider |
| `SHIVA_AUTH_KEY` | A secret of your choosing. Required for callers to invoke this server — see below. |

You may also need to configure the API endpoint URL in the code if using a different provider.

Redeploy after adding environment variables — they only apply to deployments created after
they're set.

**Set `SHIVA_AUTH_KEY`.** The endpoint is public once deployed — anyone with the URL can call
`invoke_shiva` and spend your `ABLIT_KEY` quota against an unmoderated model if no key is set.
When `SHIVA_AUTH_KEY` is set, every request must include a matching `x-shiva-key` header or it's
rejected with a 401. If you connect via Claude.ai's custom MCP server UI and it doesn't support
custom headers, front the endpoint with Vercel Deployment Protection instead.

### 4. Verify the deployment

```bash
curl https://<your-project>.vercel.app/api/mcp
```

A `405 Method Not Allowed` with a JSON-RPC error body confirms the function is
alive and speaking MCP correctly:

```json
{"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."},"id":null}
```

A `500 FUNCTION_INVOCATION_FAILED` usually means a missing dependency or env
var — check `vercel get-runtime-logs` or the dashboard's Runtime Logs tab.

### 5. Connect to Claude.ai

**Settings → Integrations → Add custom MCP server**

```
https://<your-project>.vercel.app/api/mcp
```

Once connected, the `invoke_shiva` tool becomes available to Claude.

### 6. Install the skill

Copy `skill/shiva-SKILL.md` to `/mnt/skills/user/shiva/SKILL.md` in your
Claude.ai environment. This tells Claude when and how to invoke Shiva — only
on explicit request ("summon Shiva", "run Shiva"), never proactively.

---

## Usage

In any Claude.ai conversation:

> summon Shiva

Claude will optionally pull recent context from your chosen corpus source
(Claude memory, a second-brain tool, or manual input), call `invoke_shiva`, and
return the response exactly as received. No preamble, no wrapper, no commentary.

To fire without any corpus context, just ask directly — the tool works with
no arguments.

### Corpus Context Options

You can provide corpus context through:
- **Claude Memory**: Store relevant context in your Claude memory for Shiva to access
- **Second-brain tools**: Connect a note-taking or knowledge management system
- **Direct input**: Manually provide context in your request to Shiva

---

## Editing Shiva

To change who Shiva is or how it speaks, edit only `api/prompt.js`. It's a
single exported string (`SHIVA_SYSTEM_PROMPT`). Commit and push — Vercel
redeploys automatically. `api/mcp.js` never needs to change for prompt edits.

---

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `500 FUNCTION_INVOCATION_FAILED`, `ERR_MODULE_NOT_FOUND` | Missing dependency in `package.json` — confirm `mcp-handler` + `@modelcontextprotocol/sdk` are both listed, not just `mcp-handler` |
| Tool call times out at ~30s | Model response slower than `vercel.json`'s `maxDuration` — increase it (max 60s on most plans, higher on Pro/Enterprise) |
| Tool call fails with `ABLIT_KEY environment variable not set` | Env var missing or set only on a different environment (e.g. Preview vs Production) — check it's set for Production and redeploy |
| `invoke_shiva` not visible in Claude | MCP server not added in Claude.ai Integrations, or added but using the wrong URL (must end in `/api/mcp`) |
| Tool call fails with `401 Unauthorized` | `SHIVA_AUTH_KEY` is set on the server but the caller isn't sending a matching `x-shiva-key` header |
| Shiva sounds like it's "performing" depth | Prompt drift — re-read `api/prompt.js`'s closing rule about not sounding like a performance of depth, tighten the prompt |

---

## Configuration Notes

- **API endpoint**: Currently configured for a specific model provider. To use a different provider, update the fetch URL in `api/mcp.js` and adjust the request/response format as needed.
- **Model parameters**: Adjust `model`, `stream`, and `thinking` fields in `api/mcp.js` to match your provider's API.
- **Timeouts**: Modify `maxDuration` in `vercel.json` if responses take longer than the current limit.