@siddharth.sharma/mcp-core 0.1.1 → 1.0.0

package/README.md

@@ -1,3 +1,13 @@
 # @siddharth.sharma/mcp-core
 
-Shared runtime types and utilities used by `@siddharth.sharma/*` MCP packages.
+Shared runtime types and env utilities used by first-party Valkyrie MCP packages.
+
+> `@siddharth.sharma/mcp-core` is an internal dependency package.
+> It is not a standalone MCP server and is not intended to be run directly by end users.
+
+This package has no standalone MCP server entrypoint; it is consumed by:
+
+- `@siddharth.sharma/jenkins-mcp`
+- `@siddharth.sharma/testrail-mcp`
+- `@siddharth.sharma/db-mcp`
+- `@siddharth.sharma/product-mcp-server`

package/dist/dist/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { FirstPartyMcpProduct, StreamableMcpProductConfig, StreamableMcpProductInput, StreamableMcpSessionBase, StreamableMcpSessionCreateContext, UserPlatformSecrets, ValkyriePlatformSecretKey, } from "./types.js";
+export { VALKYRIE_PLATFORM_SECRET_KEYS } from "./types.js";
+export { loadEnvFromAncestors } from "./load-env.js";
+export { readSecretJsonRaw } from "./read-secret-json.js";

package/dist/dist/dist/index.js

@@ -0,0 +1,3 @@
+export { VALKYRIE_PLATFORM_SECRET_KEYS } from "./types.js";
+export { loadEnvFromAncestors } from "./load-env.js";
+export { readSecretJsonRaw } from "./read-secret-json.js";

package/dist/dist/dist/load-env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Populate process.env from the nearest `.env` walking up from `startDir`.
+ * Existing process.env values from shell/launcher take precedence.
+ */
+export declare function loadEnvFromAncestors(startDir: string, maxDepth?: number): void;

package/dist/dist/dist/load-env.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { config as loadDotenvFile } from "dotenv";
+/**
+ * Populate process.env from the nearest `.env` walking up from `startDir`.
+ * Existing process.env values from shell/launcher take precedence.
+ */
+export function loadEnvFromAncestors(startDir, maxDepth = 16) {
+    let dir = resolve(startDir);
+    for (let i = 0; i < maxDepth; i++) {
+        const envPath = resolve(dir, ".env");
+        if (existsSync(envPath)) {
+            loadDotenvFile({ path: envPath });
+            return;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+}

package/dist/dist/dist/read-secret-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve raw secret JSON from env. Precedence:
+ * 1) inline JSON env var
+ * 2) file path env var
+ */
+export declare function readSecretJsonRaw(inlineEnvVar: string, fileEnvVar: string): string | undefined;

package/dist/dist/dist/read-secret-json.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Resolve raw secret JSON from env. Precedence:
+ * 1) inline JSON env var
+ * 2) file path env var
+ */
+export function readSecretJsonRaw(inlineEnvVar, fileEnvVar) {
+    const inline = process.env[inlineEnvVar]?.trim();
+    if (inline) {
+        return inline;
+    }
+    const filePath = process.env[fileEnvVar]?.trim();
+    if (!filePath) {
+        return undefined;
+    }
+    const resolvedPath = resolve(filePath);
+    if (!existsSync(resolvedPath)) {
+        throw new Error(`Missing secret JSON file at ${resolvedPath} (from ${fileEnvVar})`);
+    }
+    const raw = readFileSync(resolvedPath, "utf8").trim();
+    if (!raw) {
+        throw new Error(`Secret JSON file is empty at ${resolvedPath} (from ${fileEnvVar})`);
+    }
+    return raw;
+}

package/dist/dist/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { Request, Response } from "express";
+/** Minimal session shape — SDK transport handles MCP JSON-RPC. */
+export type StreamableMcpSessionBase = {
+    transport: {
+        handleRequest(req: Request, res: Response, body: unknown): Promise<void>;
+    };
+};
+/** Platform ids aligned with wrapper per-user secret paths (`…/{user}/{platform}`). */
+export declare const VALKYRIE_PLATFORM_SECRET_KEYS: readonly ["jenkins", "testrail", "database", "product"];
+export type ValkyriePlatformSecretKey = (typeof VALKYRIE_PLATFORM_SECRET_KEYS)[number];
+/** Parsed JSON payloads keyed by integration; hub fills this from AWS SSM parameter storage. */
+export type UserPlatformSecrets = Partial<Record<ValkyriePlatformSecretKey, Record<string, unknown>>>;
+/** Passed into `createSession` on the first Streamable HTTP request (new session). */
+export type StreamableMcpSessionCreateContext = {
+    /** From `x-valkyrie-user` when the gateway forwards it */
+    valkyrieUser?: string;
+    /** Per-integration secrets for this session (hub-loaded or injected in tests) */
+    userPlatformSecrets?: UserPlatformSecrets;
+};
+export type StreamableMcpProductConfig = {
+    id: string;
+    displayName: string;
+    version: string;
+    mcpServerName?: string;
+    mcpServerVersion?: string;
+};
+/** One MCP product mounted at `/${config.id}/mcp`. */
+export type StreamableMcpProductInput<S extends StreamableMcpSessionBase> = {
+    config: StreamableMcpProductConfig;
+    toolCount: number;
+    sessions: Map<string, S>;
+    createSession(ctx?: StreamableMcpSessionCreateContext): Promise<S>;
+    /** GET probe without `Mcp-Session-Id` — defaults from options.fallbackProbeCapabilities */
+    probeCapabilities?: string[];
+    /** Default `name` in GET probe when `config.mcpServerName` is unset */
+    defaultMcpServerName?: string;
+};
+/** Canonical first-party integration contract used across Valkyrie packages. */
+export type FirstPartyMcpProduct<S extends StreamableMcpSessionBase> = StreamableMcpProductInput<S>;

package/dist/dist/dist/types.js

@@ -0,0 +1,7 @@
+/** Platform ids aligned with wrapper per-user secret paths (`…/{user}/{platform}`). */
+export const VALKYRIE_PLATFORM_SECRET_KEYS = [
+    "jenkins",
+    "testrail",
+    "database",
+    "product",
+];

package/dist/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { FirstPartyMcpProduct, StreamableMcpProductConfig, StreamableMcpProductInput, StreamableMcpSessionBase, StreamableMcpSessionCreateContext, UserPlatformSecrets, ValkyriePlatformSecretKey, } from "./types.js";
+export { VALKYRIE_PLATFORM_SECRET_KEYS } from "./types.js";
+export { loadEnvFromAncestors } from "./load-env.js";
+export { readSecretJsonRaw } from "./read-secret-json.js";

package/dist/dist/index.js

@@ -0,0 +1,3 @@
+export { VALKYRIE_PLATFORM_SECRET_KEYS } from "./types.js";
+export { loadEnvFromAncestors } from "./load-env.js";
+export { readSecretJsonRaw } from "./read-secret-json.js";

package/dist/dist/load-env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Populate process.env from the nearest `.env` walking up from `startDir`.
+ * Existing process.env values from shell/launcher take precedence.
+ */
+export declare function loadEnvFromAncestors(startDir: string, maxDepth?: number): void;

package/dist/dist/load-env.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { config as loadDotenvFile } from "dotenv";
+/**
+ * Populate process.env from the nearest `.env` walking up from `startDir`.
+ * Existing process.env values from shell/launcher take precedence.
+ */
+export function loadEnvFromAncestors(startDir, maxDepth = 16) {
+    let dir = resolve(startDir);
+    for (let i = 0; i < maxDepth; i++) {
+        const envPath = resolve(dir, ".env");
+        if (existsSync(envPath)) {
+            loadDotenvFile({ path: envPath });
+            return;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+}

package/dist/dist/read-secret-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve raw secret JSON from env. Precedence:
+ * 1) inline JSON env var
+ * 2) file path env var
+ */
+export declare function readSecretJsonRaw(inlineEnvVar: string, fileEnvVar: string): string | undefined;

package/dist/dist/read-secret-json.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Resolve raw secret JSON from env. Precedence:
+ * 1) inline JSON env var
+ * 2) file path env var
+ */
+export function readSecretJsonRaw(inlineEnvVar, fileEnvVar) {
+    const inline = process.env[inlineEnvVar]?.trim();
+    if (inline) {
+        return inline;
+    }
+    const filePath = process.env[fileEnvVar]?.trim();
+    if (!filePath) {
+        return undefined;
+    }
+    const resolvedPath = resolve(filePath);
+    if (!existsSync(resolvedPath)) {
+        throw new Error(`Missing secret JSON file at ${resolvedPath} (from ${fileEnvVar})`);
+    }
+    const raw = readFileSync(resolvedPath, "utf8").trim();
+    if (!raw) {
+        throw new Error(`Secret JSON file is empty at ${resolvedPath} (from ${fileEnvVar})`);
+    }
+    return raw;
+}

package/dist/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { Request, Response } from "express";
+/** Minimal session shape — SDK transport handles MCP JSON-RPC. */
+export type StreamableMcpSessionBase = {
+    transport: {
+        handleRequest(req: Request, res: Response, body: unknown): Promise<void>;
+    };
+};
+/** Platform ids aligned with wrapper per-user secret paths (`…/{user}/{platform}`). */
+export declare const VALKYRIE_PLATFORM_SECRET_KEYS: readonly ["jenkins", "testrail", "database", "product"];
+export type ValkyriePlatformSecretKey = (typeof VALKYRIE_PLATFORM_SECRET_KEYS)[number];
+/** Parsed JSON payloads keyed by integration; hub fills this from AWS SSM parameter storage. */
+export type UserPlatformSecrets = Partial<Record<ValkyriePlatformSecretKey, Record<string, unknown>>>;
+/** Passed into `createSession` on the first Streamable HTTP request (new session). */
+export type StreamableMcpSessionCreateContext = {
+    /** From `x-valkyrie-user` when the gateway forwards it */
+    valkyrieUser?: string;
+    /** Per-integration secrets for this session (hub-loaded or injected in tests) */
+    userPlatformSecrets?: UserPlatformSecrets;
+};
+export type StreamableMcpProductConfig = {
+    id: string;
+    displayName: string;
+    version: string;
+    mcpServerName?: string;
+    mcpServerVersion?: string;
+};
+/** One MCP product mounted at `/${config.id}/mcp`. */
+export type StreamableMcpProductInput<S extends StreamableMcpSessionBase> = {
+    config: StreamableMcpProductConfig;
+    toolCount: number;
+    sessions: Map<string, S>;
+    createSession(ctx?: StreamableMcpSessionCreateContext): Promise<S>;
+    /** GET probe without `Mcp-Session-Id` — defaults from options.fallbackProbeCapabilities */
+    probeCapabilities?: string[];
+    /** Default `name` in GET probe when `config.mcpServerName` is unset */
+    defaultMcpServerName?: string;
+};
+/** Canonical first-party integration contract used across Valkyrie packages. */
+export type FirstPartyMcpProduct<S extends StreamableMcpSessionBase> = StreamableMcpProductInput<S>;

package/dist/dist/types.js

@@ -0,0 +1,7 @@
+/** Platform ids aligned with wrapper per-user secret paths (`…/{user}/{platform}`). */
+export const VALKYRIE_PLATFORM_SECRET_KEYS = [
+    "jenkins",
+    "testrail",
+    "database",
+    "product",
+];

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { FirstPartyMcpProduct, StreamableMcpProductConfig, StreamableMcpProductInput, StreamableMcpSessionBase, StreamableMcpSessionCreateContext, UserPlatformSecrets, ValkyriePlatformSecretKey, } from "./types.js";
+export { VALKYRIE_PLATFORM_SECRET_KEYS } from "./types.js";
+export { loadEnvFromAncestors } from "./load-env.js";
+export { readSecretJsonRaw } from "./read-secret-json.js";

package/dist/load-env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Populate process.env from the nearest `.env` walking up from `startDir`.
+ * Existing process.env values from shell/launcher take precedence.
+ */
+export declare function loadEnvFromAncestors(startDir: string, maxDepth?: number): void;

package/dist/read-secret-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve raw secret JSON from env. Precedence:
+ * 1) inline JSON env var
+ * 2) file path env var
+ */
+export declare function readSecretJsonRaw(inlineEnvVar: string, fileEnvVar: string): string | undefined;

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { Request, Response } from "express";
+/** Minimal session shape — SDK transport handles MCP JSON-RPC. */
+export type StreamableMcpSessionBase = {
+    transport: {
+        handleRequest(req: Request, res: Response, body: unknown): Promise<void>;
+    };
+};
+/** Platform ids aligned with wrapper per-user secret paths (`…/{user}/{platform}`). */
+export declare const VALKYRIE_PLATFORM_SECRET_KEYS: readonly ["jenkins", "testrail", "database", "product"];
+export type ValkyriePlatformSecretKey = (typeof VALKYRIE_PLATFORM_SECRET_KEYS)[number];
+/** Parsed JSON payloads keyed by integration; hub fills this from AWS SSM parameter storage. */
+export type UserPlatformSecrets = Partial<Record<ValkyriePlatformSecretKey, Record<string, unknown>>>;
+/** Passed into `createSession` on the first Streamable HTTP request (new session). */
+export type StreamableMcpSessionCreateContext = {
+    /** From `x-valkyrie-user` when the gateway forwards it */
+    valkyrieUser?: string;
+    /** Per-integration secrets for this session (hub-loaded or injected in tests) */
+    userPlatformSecrets?: UserPlatformSecrets;
+};
+export type StreamableMcpProductConfig = {
+    id: string;
+    displayName: string;
+    version: string;
+    mcpServerName?: string;
+    mcpServerVersion?: string;
+};
+/** One MCP product mounted at `/${config.id}/mcp`. */
+export type StreamableMcpProductInput<S extends StreamableMcpSessionBase> = {
+    config: StreamableMcpProductConfig;
+    toolCount: number;
+    sessions: Map<string, S>;
+    createSession(ctx?: StreamableMcpSessionCreateContext): Promise<S>;
+    /** GET probe without `Mcp-Session-Id` — defaults from options.fallbackProbeCapabilities */
+    probeCapabilities?: string[];
+    /** Default `name` in GET probe when `config.mcpServerName` is unset */
+    defaultMcpServerName?: string;
+};
+/** Canonical first-party integration contract used across Valkyrie packages. */
+export type FirstPartyMcpProduct<S extends StreamableMcpSessionBase> = StreamableMcpProductInput<S>;

package/docs/README.md

@@ -0,0 +1,11 @@
+# mcp-core package docs
+
+Shared runtime helpers for first-party packages.
+
+## Scope
+
+- Environment loading utilities.
+- Shared secret JSON parsing helpers.
+- Shared runtime types.
+
+This package intentionally has no runtime MCP server or secret sample payloads.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siddharth.sharma/mcp-core",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "Shared Valkyrie MCP runtime types and env helpers",
   "type": "module",
   "private": false,
@@ -14,11 +14,16 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "engines": {
     "node": ">=22.18.0"
   },
+  "scripts": {
+    "build:pkg": "tsc -p tsconfig.build.json",
+    "copy:assets": "cpy \"**/*\" \"dist\" --cwd \"../../src/mcp-core\" --parents --ignore \"**/*.ts\" --ignore \"**/*.tsx\" --ignore \"**/*.mts\" --ignore \"**/*.cts\" --ignore \"dist/**\" --ignore \"**/dist/**\""
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"