Vesper MCP server

claude mcp add --transport http vesper http://127.0.0.1:8000/mcp

{
  "mcpServers": {
    "vesper": { "type": "http", "url": "http://127.0.0.1:8000/mcp" }
  }
}

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "vesper": { "url": "http://127.0.0.1:8000/mcp", "headers": { "Authorization": "Bearer ${VESPER_TOKEN}" } }
  }
}

// .vscode/mcp.json
{
  "servers": {
    "vesper": { "type": "http", "url": "http://127.0.0.1:8000/mcp" }
  }
}

{
  "sessionId": "VS-1a0a7062e0d-5e630a",
  "state": "blocked",
  "reply": { "text": "Logging the observation is not allowed yet. At Zone C, Level 4, the hot work permit HWP-2031 has mandatory checks still pending: Fire watcher assigned …" }
}

# manifest
curl -s http://127.0.0.1:8000/api/tools

# call a tool
curl -s http://127.0.0.1:8000/api/tools/list_permits -H 'Content-Type: application/json' -d '{"projectId":"NSK"}'
# → {"ok": true, "tool": "list_permits", "result": [...]}

# pip install mcp
import asyncio, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = os.getenv("VESPER_MCP_URL", "http://127.0.0.1:8000/mcp")
HEADERS = {"Authorization": f"Bearer {os.environ['VESPER_TOKEN']}"} if os.getenv("VESPER_TOKEN") else {}

async def main():
    async with streamablehttp_client(URL, headers=HEADERS) as (read, write, _):
        async with ClientSession(read, write) as s:
            await s.initialize()
            tools = await s.list_tools()
            print([t.name for t in tools.tools])
            r = await s.call_tool("ask_memory", {"query": "Which permits are blocking work today?", "projectId": "NSK"})
            print(r.structuredContent["answer"])

asyncio.run(main())

# pip install httpx
import itertools, os, httpx

class Vesper:
    def __init__(self, url="http://127.0.0.1:8000/mcp", token=os.getenv("VESPER_TOKEN")):
        self.url, self.ids = url, itertools.count(1)
        self.http = httpx.Client(timeout=180, headers={"Authorization": f"Bearer {token}"} if token else {})

    def rpc(self, method, params=None):
        r = self.http.post(self.url, json={"jsonrpc": "2.0", "id": next(self.ids), "method": method, "params": params or {}})
        body = r.json()
        if "error" in body: raise RuntimeError(body["error"])
        return body["result"]

    def call(self, name, **args):
        res = self.rpc("tools/call", {"name": name, "arguments": args})
        if res["isError"]: raise RuntimeError(res["content"][0]["text"])
        return res["structuredContent"]

v = Vesper()
v.rpc("initialize")
print(v.call("ask_memory", query="Who is the structural consultant?", projectId="NSK")["answer"])
verdict = v.call("check_site_statement", projectId="NSK", text="Sump ki excavation restart karo")
print(verdict["state"], verdict["reply"]["text"])

# pip install openai-agents
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(url="http://127.0.0.1:8000/mcp") as vesper:
        agent = Agent(name="Site QA", mcp_servers=[vesper],
                      instructions="Answer only from Vesper tools. Always pass projectId.")
        out = await Runner.run(agent, "What blocks the L3 OT slab pour on project NSK?")
        print(out.final_output)

asyncio.run(main())

// npm i @modelcontextprotocol/sdk
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL(process.env.VESPER_MCP_URL ?? "http://127.0.0.1:8000/mcp"), {
  requestInit: { headers: process.env.VESPER_TOKEN ? { Authorization: `Bearer ${process.env.VESPER_TOKEN}` } : {} },
});
const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

const res = await client.callTool({ name: "list_permits", arguments: { projectId: "NSK" } });
console.log(res.structuredContent);

const URL_ = process.env.VESPER_MCP_URL ?? "http://127.0.0.1:8000/mcp";
let id = 0;

export async function vesper<T = unknown>(name: string, args: Record<string, unknown> = {}): Promise<T> {
  const r = await fetch(URL_, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...(process.env.VESPER_TOKEN ? { Authorization: `Bearer ${process.env.VESPER_TOKEN}` } : {}) },
    body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }),
  });
  const body = await r.json();
  if (body.error) throw new Error(body.error.message);
  if (body.result.isError) throw new Error(body.result.content[0].text);
  return body.result.structuredContent as T;
}

const a = await vesper<{ answer: string; abstain: boolean }>("ask_memory", { query: "Who is the structural consultant?", projectId: "NSK" });
console.log(a.abstain ? "not in the record" : a.answer);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func call(name string, args map[string]any) (map[string]any, error) {
	body, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
		"params": map[string]any{"name": name, "arguments": args}})
	req, _ := http.NewRequest("POST", "http://127.0.0.1:8000/mcp", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	if t := os.Getenv("VESPER_TOKEN"); t != "" {
		req.Header.Set("Authorization", "Bearer "+t)
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	var out struct {
		Result struct {
			StructuredContent map[string]any `json:"structuredContent"`
			IsError           bool           `json:"isError"`
		} `json:"result"`
	}
	return out.Result.StructuredContent, json.NewDecoder(resp.Body).Decode(&out)
}

func main() {
	r, err := call("ask_memory", map[string]any{"query": "What cover does IS 456 require for columns?", "projectId": "P1"})
	fmt.Println(r["answer"], err)
}

curl -s $VESPER_MCP_URL -H 'Content-Type: application/json' -H "Authorization: Bearer $VESPER_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

curl -s $VESPER_MCP_URL -H 'Content-Type: application/json' -H "Authorization: Bearer $VESPER_TOKEN" -d '{
  "jsonrpc":"2.0","id":2,"method":"tools/call",
  "params":{"name":"check_site_statement","arguments":{"projectId":"NSK","text":"Level 3 OT slab ka concrete pour start karte hain"}}}'

curl -s http://127.0.0.1:8000/api/tools/search_memory -H 'Content-Type: application/json' \
  -d '{"query":"IS 456 clause 26.4 cover","projectId":"P1","k":5}'

TOOLS.append({
    "name": "list_submittals",
    "title": "List submittals",
    "description": "Submittals with review status and spec references.",
    "inputSchema": {"type": "object", "properties": {"projectId": _PID}, "required": ["projectId"]},
    "annotations": _RO,
})
_BY_NAME["list_submittals"] = TOOLS[-1]

# in run_tool():
if name == "list_submittals":
    return await _call(request, "GET", "/api/submittals", params={"projectId": pid})

GROQ_API_KEY=            # answer phrasing (Cerebras fallback: CEREBRAS_API_KEY)
CLERK_JWT_ISSUER=        # empty = local header auth; set in production
MEMORY_COGNEE_ENABLED=1  # knowledge graph (optional)