@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-rt/lib/src/types/ringbuffer.cpp

@@ -0,0 +1,336 @@
+#include <types/ringbuffer.h>
+
+#include <boost/beast.hpp>
+
+#include <yas/buffers.hpp>
+#include <yas/serialize.hpp>
+#include <yas/std_types.hpp>
+
+#include <types/data.h>
+
+namespace beast = boost::beast;
+
+namespace hkp {
+
+unsigned int FloatRingBuffer::m_bufferAutoId = 0;
+
+FloatRingBuffer::FloatRingBuffer(std::string name) 
+  : m_name(name), 
+    m_id(m_bufferAutoId++),  
+    m_writeIndex(0), m_readIndex(0),
+    m_timestamp(timeSinceEpochMillisec())
+{
+  memset(m_buffer, 0, sizeof(m_buffer));
+}
+
+void FloatRingBuffer::append(float value)
+{
+  const auto writeIndex = m_writeIndex.load(std::memory_order_relaxed);
+  m_buffer[writeIndex % N] = value;
+  m_writeIndex.store(writeIndex + 1, std::memory_order_release);
+}
+
+unsigned int FloatRingBuffer::appendBinary(const char *data, unsigned int count)
+{
+  // std::cout << "FloatRingBuffer.appendBinary: " << m_name << " count: " << count / sizeof(float) << " readpos: " << m_readIndex << " writepos: " << m_writeIndex << std::endl;
+  auto numItems = count / sizeof(float);
+
+  // Realtime-safe: called from the audio callback. Samples first, index last.
+  const float *src = reinterpret_cast<const float *>(data);
+  const auto writeIndex = m_writeIndex.load(std::memory_order_relaxed);
+  for (unsigned int i = 0; i < numItems; ++i, ++src)
+  {
+    m_buffer[(writeIndex + i) % N] = *src;
+  }
+  m_writeIndex.store(writeIndex + numItems, std::memory_order_release);
+  return numItems;
+}
+
+unsigned int FloatRingBuffer::appendAvailable(FloatRingBuffer& source, bool advanceReadIndex)
+{
+  auto srcReadIndex = source.m_readIndex.load(std::memory_order_relaxed);
+  auto srcWriteIndex = source.m_writeIndex.load(std::memory_order_acquire);
+  uint64_t availableSamples = srcWriteIndex - srcReadIndex;
+
+  if (availableSamples > N)
+  {
+    std::cerr << "FloatRingBuffer::appendAvailable the source buffer wrapped twice - increase the buffer size - Resetting indices" << std::endl;
+    srcReadIndex = srcWriteIndex - N;
+    availableSamples = N; // reset to max size
+  }
+
+  const auto writeIndex = m_writeIndex.load(std::memory_order_relaxed);
+  for (uint64_t i = 0; i < availableSamples; ++i)
+  {
+    m_buffer[(writeIndex + i) % N] = source.m_buffer[(srcReadIndex + i) % N];
+  }
+  m_writeIndex.store(writeIndex + availableSamples, std::memory_order_release);
+
+  if (advanceReadIndex)
+  {
+    source.m_readIndex.store(srcReadIndex + availableSamples); // move read index forward
+  }
+  return static_cast<unsigned int>(availableSamples);
+}
+
+unsigned int FloatRingBuffer::consumeAvailable(FloatRingBuffer& target)
+{
+  return target.appendAvailable(*this, true); // append to self
+}
+
+unsigned int FloatRingBuffer::consumeAvailableByAppend(std::vector<uint8_t>& target)
+{
+  auto srcReadIndex = m_readIndex.load(std::memory_order_relaxed);
+  auto srcWriteIndex = m_writeIndex.load(std::memory_order_acquire);
+  uint64_t availableSamples = srcWriteIndex - srcReadIndex;
+  if (availableSamples > N)
+  {
+    std::cerr << "FloatRingBuffer::appendAvailable the source buffer wrapped twice - increase the buffer size - Resetting indices" << std::endl;
+    srcReadIndex = srcWriteIndex - N;
+    availableSamples = N; // reset to max size
+  }
+  target.reserve(target.size() + availableSamples * sizeof(float));
+  for (uint64_t i = 0; i < availableSamples; ++i)
+  {
+    float value = m_buffer[(srcReadIndex + i) % N];
+    target.insert(
+      target.end(),
+      reinterpret_cast<const uint8_t*>(&value),
+      reinterpret_cast<const uint8_t*>(&value) + sizeof(float)
+    );
+  } 
+
+  m_readIndex.store(srcReadIndex + availableSamples); // move read index forward
+  return static_cast<unsigned int>(availableSamples);
+}
+
+unsigned int FloatRingBuffer::consumeBinary(float *outputBuffer, unsigned int frameCount, unsigned int numChannels)
+{
+  // std::cout << "FloatRingBuffer.consume: " << m_name << " count: " << frameCount << " readpos: " << m_readIndex << " writepos: " << m_writeIndex << std::endl;
+  unsigned int availableSamples = m_writeIndex - m_readIndex;
+  unsigned int framesToCopy = std::min(availableSamples, frameCount);
+  for (unsigned int i = 0; i < framesToCopy; ++i, ++m_readIndex)
+  {
+    for (unsigned int j = 0; j < numChannels; ++j)
+    {
+      outputBuffer[i * numChannels + j] = m_buffer[m_readIndex % N]; // TODO: copies mono to all channels
+    }
+  }
+
+  unsigned int numFillFrames = frameCount - framesToCopy;
+  if (numFillFrames > 0)
+  {
+    for (unsigned int i = 0; i < numFillFrames; ++i)
+    {
+      for (unsigned int j = 0; j < numChannels; ++j)
+      {
+        outputBuffer[(framesToCopy + i) * numChannels + j] = 0;
+      }
+    }
+    std::cout << "Filled " << numFillFrames << " samples (w: "<< m_writeIndex << ") \r" << std::flush;
+  }
+  return framesToCopy;
+}
+
+unsigned int FloatRingBuffer::consumeExact(std::vector<float>& target, unsigned int count)
+{
+  unsigned int available = m_writeIndex - m_readIndex;
+  if (available > count)
+  {
+    // Drop stale samples — skip ahead so we always consume the freshest `count` samples.
+    m_readIndex += (available - count);
+  }
+  else if (available < count)
+  {
+    // Not enough data yet; don't consume anything.
+    return 0;
+  }
+
+  target.resize(count);
+  for (unsigned int i = 0; i < count; ++i)
+  {
+    target[i] = m_buffer[(m_readIndex + i) % N];
+  }
+  m_readIndex += count;
+  return count;
+}
+
+void FloatRingBuffer::skipSamples(unsigned int count)
+{
+  unsigned int available = m_writeIndex - m_readIndex;
+  m_readIndex += std::min(count, available);
+}
+
+unsigned int FloatRingBuffer::consumeAvailable(std::vector<float>& target, bool advanceReadIndex) const
+{
+  unsigned int availableSamples = m_writeIndex - m_readIndex;
+  if (availableSamples > N)
+  {
+    std::cerr << "FloatRingBuffer::copyAvailable the write buffer wrapped twice - increase the buffer size - Resetting indices" << std::endl;
+    if (advanceReadIndex)
+    {
+      m_readIndex.store(m_writeIndex - N);
+    }
+    availableSamples = N; // reset to max size
+  }
+
+  target.resize(availableSamples);
+  for (unsigned int i = 0; i < availableSamples; ++i)
+  {
+    target[i] = m_buffer[(m_readIndex + i) % N];
+  }
+
+  if (advanceReadIndex)
+  {
+    m_readIndex += availableSamples; // move read index forward
+  }
+    
+  return availableSamples;
+}
+
+unsigned int FloatRingBuffer::consumeAvailable(std::vector<uint8_t>& target, bool advanceReadIndex) const
+{
+  unsigned int availableSamples = m_writeIndex - m_readIndex;
+  if (availableSamples > N)
+  {
+    std::cerr << "FloatRingBuffer::copyAvailable the write buffer wrapped twice - increase the buffer size - Resetting indices" << std::endl;
+    if (advanceReadIndex)
+    {
+      m_readIndex.store(m_writeIndex - N);
+    }
+    availableSamples = N; // reset to max size
+  }
+
+  target.resize(availableSamples * sizeof(float));
+  for (unsigned int i = 0; i < availableSamples; ++i)
+  {
+    float value = m_buffer[(m_readIndex + i) % N];
+    std::memcpy(&target[i * sizeof(float)], &value, sizeof(float));
+  }
+
+  if (advanceReadIndex)
+  {
+    m_readIndex += availableSamples; // move read index forward
+  }
+    
+  return availableSamples;
+}
+
+void FloatRingBuffer::resyncIfNeeded() 
+{
+   unsigned int availableSamples = m_writeIndex - m_readIndex;
+  if (availableSamples > N)
+  {
+    std::cout << "FloatRingBuffer::serialise the write buffer wrapped twice - increase the buffer size - Resetting indices" << std::endl;
+    m_readIndex.store(m_writeIndex - N);
+  }
+}
+
+yas::shared_buffer FloatRingBuffer::serialise() const
+{
+  unsigned int availableSamples = m_writeIndex - m_readIndex;
+  if (availableSamples > N)
+  {
+    std::cerr << "FloatRingBuffer::serialise the write buffer wrapped twice - increase the buffer size - Resetting indices" << std::endl;
+    m_readIndex.store(m_writeIndex - N);
+  }
+
+  auto numSavedSamples = std::min(availableSamples, N);
+  float continuousBuffer[N]; // contains all samples in one continuous buffer
+  for (unsigned int i = 0; i < numSavedSamples; ++i)
+  {
+    continuousBuffer[i] = m_buffer[(m_readIndex + i) % N];
+  }
+  m_readIndex += numSavedSamples;
+
+  constexpr std::size_t flags = yas::mem | yas::binary;
+  auto o = YAS_OBJECT_NVP(nullptr,
+                          ("type", getTypeId<FloatRingBuffer>()),
+                          ("array", yas::array(&continuousBuffer[0], numSavedSamples)),
+                          ("id", m_id), 
+                          ("ts", timeSinceEpochMillisec())
+                        );
+  return yas::save<flags>(o);
+}
+
+// TODO: should be renamed to not contain create in the name
+void FloatRingBuffer::createFromSerialised(BufferType& buffer, unsigned int size, FloatRingBuffer& target)
+{
+  const char *rawData = reinterpret_cast<const char *>(buffer.data().data());
+  yas::intrusive_buffer buf(rawData, buffer.size());
+
+  float *iptr = nullptr;
+  std::size_t isize = 0;
+  auto arrholder = yas::array(&iptr, &isize);
+
+  unsigned int id = 0;
+  uint64_t ts = 0;
+  unsigned int type;
+  auto iobj = YAS_OBJECT_NVP(
+    nullptr,
+    ("type", type),
+    ("array", arrholder), 
+    ("id", id), 
+    ("ts", ts)
+  );
+  
+
+  constexpr std::size_t flags = yas::mem | yas::binary;
+  yas::load<flags>(buf, iobj);
+  
+  if (type != getTypeId<FloatRingBuffer>())
+  {
+    std::cerr << "FloatRingBuffer::createFromSerialised: type mismatch - got: " << type << std::endl;
+    return;
+  }
+
+  target.appendBinary(reinterpret_cast<char *>(iptr), isize * sizeof(float));
+  target.m_id = id;
+  target.m_timestamp = ts;
+
+  auto delta = target.age();
+  static unsigned int averageTs = 0;
+  static unsigned int count = 0;
+  averageTs += delta;
+  if (++count % 10 == 0)
+  {
+    std::cout << "FloatRingBuffer::createFromSerialised round-trip latency: " << averageTs / static_cast<float>(count) << "msec" << std::endl;
+    averageTs = 0;
+    count = 0;
+  }
+
+  arrholder.free(iptr);
+}
+
+uint64_t FloatRingBuffer::timeSinceEpochMillisec()
+{
+  using namespace std::chrono;
+  return duration_cast<milliseconds>(system_clock::now().time_since_epoch()).count();
+}
+
+uint64_t FloatRingBuffer::age() const
+{
+  auto currentTs = timeSinceEpochMillisec();
+  auto delta = currentTs - m_timestamp;
+  return delta;
+}
+
+unsigned int FloatRingBuffer::availableCount() const
+{
+  return m_writeIndex - m_readIndex;
+}
+
+std::ostream& operator<<(std::ostream& os, const FloatRingBuffer& data)
+{
+  os << "FloatRingBuffer: " << data.id() << " " << data.availableCount() << std::endl;
+  os << "ReadIndex: " << data.getReadIndex() << " WriteIndex: " << data.getWriteIndex() << std::endl;
+  auto idx = data.m_readIndex.load();
+  for (unsigned int i = 0; i < data.availableCount(); ++i, ++idx)
+  {
+    os << data.m_buffer[idx % FloatRingBuffer::N] << " ";
+  }
+  os << std::endl;
+  return os;
+}
+
+}

package/bundle/hkp-rt/lib/src/uuid.h

@@ -0,0 +1,12 @@
+#pragma once
+
+#include <boost/uuid/uuid.hpp>
+#include <boost/uuid/uuid_generators.hpp>
+#include <boost/uuid/uuid_io.hpp>
+
+static inline std::string generateUUID()
+{
+  boost::uuids::random_generator gen;
+  boost::uuids::uuid id = gen();
+  return boost::uuids::to_string(id);
+}

package/bundle/readymade-mcp-commits.json

@@ -0,0 +1,5 @@
+{
+  "readymade": "847c234cfc8d541396662f7d4c701018666b172e",
+  "hkp-node": "9460f14ef91594191dd52dae8cc54a1f51f73543",
+  "hkp-python": "f6d88e01c7d2cb6874b26b2e6f65f11f67f59a60"
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { findRepositoryRoot, KnowledgeRepository } from "./repository.js";
+import { createReadymadeMcpServer } from "./server.js";
+import { startHttpServer } from "./http.js";
+function parseArguments(argv) {
+    const result = {
+        stdio: false,
+        allowedHostnames: [],
+        allowedOriginHostnames: [],
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--stdio")
+            result.stdio = true;
+        else if (argument === "--host")
+            result.host = argv[++index];
+        else if (argument === "--port")
+            result.port = Number(argv[++index]);
+        else if (argument === "--root")
+            result.root = argv[++index];
+        else if (argument === "--rate-limit")
+            result.rateLimit = Number(argv[++index]);
+        else if (argument === "--allowed-host")
+            result.allowedHostnames.push(argv[++index]);
+        else if (argument === "--allowed-origin")
+            result.allowedOriginHostnames.push(argv[++index]);
+        else if (argument === "--help") {
+            process.stdout.write("Usage: readymade-mcp [--stdio] [--root PATH] [--host 127.0.0.1] [--port 8787] [--allowed-host HOSTNAME] [--allowed-origin HOSTNAME] [--rate-limit PER_MINUTE]\n" +
+                "Without --root it serves the knowledge the package ships, or the checkout it is run in.\n" +
+                "--rate-limit is requests to /mcp per client and minute (default 120; 0 for none).\n" +
+                "Set READYMADE_MCP_TOKEN to require it as a bearer token on /mcp.\n");
+            process.exit(0);
+        }
+        else
+            throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (result.port !== undefined && (!Number.isInteger(result.port) || result.port < 0 || result.port > 65_535))
+        throw new Error("--port must be an integer from 0 to 65535.");
+    if (result.rateLimit !== undefined && (!Number.isInteger(result.rateLimit) || result.rateLimit < 0))
+        throw new Error("--rate-limit must be a whole number of requests per minute, or 0 for none.");
+    return result;
+}
+// What `npm run bundle` wrote and the package ships beside dist/.
+const packageRoot = path.resolve(import.meta.dirname, "..");
+const packagedKnowledge = path.join(packageRoot, "bundle");
+async function main() {
+    const options = parseArguments(process.argv.slice(2));
+    const packaged = !options.root && existsSync(packagedKnowledge);
+    const root = options.root ? await findRepositoryRoot(options.root) : packaged ? packagedKnowledge : await findRepositoryRoot();
+    // Shipped knowledge is the package's own: its version is the build version.
+    const packageVersion = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+    const repository = await KnowledgeRepository.create(root, process.env.READYMADE_BUILD_VERSION ?? (packaged ? packageVersion : undefined));
+    if (options.stdio) {
+        serveStdio(() => createReadymadeMcpServer(repository), { onerror: (error) => console.error(error) });
+        return;
+    }
+    const { server, url } = await startHttpServer(repository, {
+        host: options.host,
+        port: options.port,
+        allowedHostnames: options.allowedHostnames,
+        allowedOriginHostnames: options.allowedOriginHostnames,
+        rateLimit: options.rateLimit,
+        // From the environment rather than an argument, which other users of the
+        // machine can read in the process list.
+        token: process.env.READYMADE_MCP_TOKEN || undefined,
+    });
+    console.log(`Readymade MCP knowledge server listening at ${url}`);
+    console.log(`Indexed ${repository.stats().documents} documents, ${repository.stats().boards} boards, and ${repository.stats().contracts} runtime-specific contracts.`);
+    const close = () => server.close(() => process.exit(0));
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/git.d.ts

@@ -0,0 +1,8 @@
+export declare function readCommit(worktree: string): Promise<string>;
+/**
+ * The commits a bundle was made from (`scripts/bundle.mjs`), keyed by
+ * repository. A bundle has no `.git` to read them from; outside one this is
+ * undefined.
+ */
+export declare function readBundleCommits(root: string): Promise<Record<string, string> | undefined>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAeA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBlE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAQjG"}

package/dist/git.js

@@ -0,0 +1,53 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+async function resolveGitDir(worktree) {
+    const marker = path.join(worktree, ".git");
+    try {
+        const value = (await readFile(marker, "utf8")).trim();
+        const match = /^gitdir:\s*(.+)$/.exec(value);
+        return match ? path.resolve(worktree, match[1]) : undefined;
+    }
+    catch (error) {
+        if (error.code === "EISDIR")
+            return marker;
+        return undefined;
+    }
+}
+export async function readCommit(worktree) {
+    const gitDir = await resolveGitDir(worktree);
+    if (!gitDir)
+        return "unknown";
+    try {
+        const head = (await readFile(path.join(gitDir, "HEAD"), "utf8")).trim();
+        if (!head.startsWith("ref: "))
+            return head;
+        const ref = head.slice(5);
+        try {
+            return (await readFile(path.join(gitDir, ref), "utf8")).trim();
+        }
+        catch {
+            const packed = await readFile(path.join(gitDir, "packed-refs"), "utf8");
+            const line = packed.split("\n").find((entry) => entry.endsWith(` ${ref}`));
+            return line?.split(" ")[0] ?? "unknown";
+        }
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * The commits a bundle was made from (`scripts/bundle.mjs`), keyed by
+ * repository. A bundle has no `.git` to read them from; outside one this is
+ * undefined.
+ */
+export async function readBundleCommits(root) {
+    try {
+        const value = JSON.parse(await readFile(path.join(root, "readymade-mcp-commits.json"), "utf8"));
+        if (typeof value !== "object" || value === null)
+            return undefined;
+        return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,17 @@
+import { type Server } from "node:http";
+import type { KnowledgeRepository } from "./repository.js";
+export interface HttpServerOptions {
+    host?: string;
+    port?: number;
+    allowedHostnames?: string[];
+    allowedOriginHostnames?: string[];
+    /** When set, /mcp requires `Authorization: Bearer <token>`. */
+    token?: string;
+    /** Requests to /mcp each client may make per minute; 0 for no limit. */
+    rateLimit?: number;
+}
+export declare function startHttpServer(repository: KnowledgeRepository, options?: HttpServerOptions): Promise<{
+    server: Server;
+    url: string;
+}>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AACA,OAAO,EAAsC,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAI5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoDD,wBAAsB,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAkFhJ"}

package/dist/http.js

@@ -0,0 +1,130 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { hostHeaderValidation, localhostHostValidation, localhostOriginValidation, originValidation, toNodeHandler } from "@modelcontextprotocol/node";
+import { createReadymadeMcpServer } from "./server.js";
+function isLoopback(host) {
+    return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+const loopbackNames = ["localhost", "127.0.0.1", "[::1]"];
+function digest(value) {
+    return createHash("sha256").update(value).digest();
+}
+/**
+ * Who a request comes from. Behind a reverse proxy on the same machine every
+ * request arrives from loopback, so there the client is the address the proxy
+ * appended last to X-Forwarded-For; from anywhere else that header is the
+ * client's own word and is ignored.
+ */
+function clientOf(request) {
+    const remote = request.socket.remoteAddress ?? "";
+    const loopback = remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
+    const forwarded = request.headers["x-forwarded-for"];
+    const last = (Array.isArray(forwarded) ? forwarded.join(",") : forwarded)?.split(",").pop()?.trim();
+    return loopback && last ? last : remote;
+}
+/**
+ * Counts requests per client in fixed one-minute windows. Answers how many
+ * seconds remain until the window ends once a client is over `limit`, and
+ * undefined while it is not. Counts are dropped with each window, so memory
+ * stays bounded by the clients of a single minute.
+ */
+function rateLimiter(limit, windowMs = 60_000) {
+    let windowStart = Date.now();
+    let counts = new Map();
+    return (client) => {
+        const now = Date.now();
+        if (now - windowStart >= windowMs) {
+            windowStart = now;
+            counts = new Map();
+        }
+        const count = (counts.get(client) ?? 0) + 1;
+        counts.set(client, count);
+        return count > limit ? Math.ceil((windowStart + windowMs - now) / 1000) : undefined;
+    };
+}
+function authorized(request, expected) {
+    const match = /^Bearer\s+(.+)$/i.exec(request.headers.authorization ?? "");
+    return match !== null && timingSafeEqual(digest(match[1].trim()), expected);
+}
+export async function startHttpServer(repository, options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? 8787;
+    if (!isLoopback(host) && (!options.allowedHostnames?.length || !options.allowedOriginHostnames?.length)) {
+        throw new Error("Non-loopback binding requires explicit allowedHostnames and allowedOriginHostnames. Put a TLS reverse proxy in front of it before exposing it publicly.");
+    }
+    const limited = options.rateLimit === 0 ? undefined : rateLimiter(options.rateLimit ?? 120);
+    const token = options.token ? digest(options.token) : undefined;
+    const validateHost = isLoopback(host)
+        ? options.allowedHostnames?.length
+            ? hostHeaderValidation([...new Set([...loopbackNames, ...options.allowedHostnames])])
+            : localhostHostValidation()
+        : hostHeaderValidation(options.allowedHostnames);
+    const validateOrigin = isLoopback(host)
+        ? options.allowedOriginHostnames?.length
+            ? originValidation([...new Set([...loopbackNames, ...options.allowedOriginHostnames])])
+            : localhostOriginValidation()
+        : originValidation(options.allowedOriginHostnames);
+    const handler = createMcpHandler(() => createReadymadeMcpServer(repository), {
+        responseMode: "auto",
+        legacy: "stateless",
+        onerror: (error) => console.error("Readymade MCP request error:", error),
+    });
+    const nodeHandler = toNodeHandler(handler, { maxRequestBodySize: 1_048_576 });
+    const server = createServer((request, response) => {
+        const pathname = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`).pathname;
+        if (!validateHost(request, response) || !validateOrigin(request, response))
+            return;
+        const origin = request.headers.origin;
+        if (origin) {
+            // No credentials: the server uses no cookies, and a bearer token is an
+            // explicit header, so an allowed origin never gets a credentialed request.
+            response.setHeader("access-control-allow-origin", origin);
+            response.setHeader("access-control-expose-headers", "Mcp-Protocol-Version, Mcp-Session-Id");
+            response.setHeader("vary", "Origin");
+        }
+        if (request.method === "OPTIONS") {
+            response.setHeader("access-control-allow-methods", "GET, POST, DELETE, OPTIONS");
+            response.setHeader("access-control-allow-headers", request.headers["access-control-request-headers"] ?? "Content-Type, Accept, Authorization, Mcp-Protocol-Version, Mcp-Session-Id, Last-Event-ID");
+            response.writeHead(204);
+            response.end();
+            return;
+        }
+        if (request.method === "GET" && pathname === "/health") {
+            response.writeHead(200, { "content-type": "application/json" });
+            response.end(JSON.stringify({ ok: true, ...repository.stats() }));
+            return;
+        }
+        if (pathname !== "/mcp") {
+            response.writeHead(404, { "content-type": "application/json" });
+            response.end(JSON.stringify({ error: "Not found" }));
+            return;
+        }
+        const retryAfter = limited?.(clientOf(request));
+        if (retryAfter !== undefined) {
+            response.writeHead(429, { "content-type": "application/json", "retry-after": String(retryAfter) });
+            response.end(JSON.stringify({ error: "Too many requests" }));
+            return;
+        }
+        if (token && !authorized(request, token)) {
+            response.writeHead(401, { "content-type": "application/json", "www-authenticate": "Bearer" });
+            response.end(JSON.stringify({ error: "Unauthorized" }));
+            return;
+        }
+        void nodeHandler(request, response);
+    });
+    // Every exchange is one bounded tool call, so a client that trickles its
+    // request is cut off instead of holding a connection open.
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 30_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const boundPort = typeof address === "object" && address ? address.port : port;
+    return { server, url: `http://${host.includes(":") ? `[${host}]` : host}:${boundPort}/mcp` };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { startHttpServer, type HttpServerOptions } from "./http.js";
+export { findRepositoryRoot, KnowledgeRepository } from "./repository.js";
+export { readymadeToolSchemas } from "./schemas.js";
+export { createReadymadeMcpServer } from "./server.js";
+export * from "./types.js";
+export { validateBoard, type ValidationCatalog } from "./validation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}