@inner-security/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inner Security
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @inner-security/mcp — Inner MCP server
+
+A **thin client** of Inner's Verdict API, exposed over the
+[Model Context Protocol](https://modelcontextprotocol.io) (stdio). It lets a
+coding agent get a verdict + a suggested safer alternative **before** it installs
+a package.
+
+All detection, scoring, and auth live **server-side**. This package ships no
+detection logic — it only consumes the Verdict API. Real usage is **gated by an
+Inner org API key** (the Datadog model).
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `check_package` | `(ecosystem, name, version)` → verdict + an alternative when blocked |
+| `check_dependencies` | manifest/lockfile or explicit list → per-package verdicts + tally |
+| `explain_verdict` | a package → deep-insight reasoning (behaviors + evidence) |
+| `suggest_alternative` | a blocked package → a safer alternative |
+| `request_review` | a package → records a review request |
+
+## Run
+
+Requires **Node >= 20**. The server speaks MCP over stdio via the `inner-mcp` bin.
+
+```bash
+npx @inner-security/mcp        # or: npm i -g @inner-security/mcp && inner-mcp
+```
+
+### Wire into an MCP client
+
+```json
+{
+  "mcpServers": {
+    "inner": {
+      "command": "npx",
+      "args": ["-y", "@inner-security/mcp"],
+      "env": {
+        "INNER_API_KEY": "ik_...",
+        "INNER_API_URL": "https://verdict.inner.example"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+Env-configurable; **defaults to dev values today** and flips to Inner's prod
+hosts once they are live (PROD-WIRING 3/4/12):
+
+| Env | Purpose | Default (dev) |
+|-----|---------|---------------|
+| `INNER_API_URL` | Verdict API base URL | `http://localhost:8787` (the local `verdict-api-mock`) |
+| `INNER_API_KEY` | Org API key (gates real verdicts) | (none) |
+
+## How verdicts resolve
+
+Package-verdict tools call `POST /v1/verdict` and handle the
+`VerdictEnvelope | PendingResponse` envelope, polling `PENDING` items with a
+per-request timeout. No local cache (unlike the CLI).
+
+## License
+
+MIT © 2026 Inner Security. See [LICENSE](./LICENSE).

package/bundle/index.d.ts

@@ -0,0 +1,136 @@
+import { VerdictClient, VerdictClientOptions } from '@inner/verdict-client';
+export { DEFAULT_API_URL, VerdictClient, VerdictClientOptions, isEnvelope, isPending } from '@inner/verdict-client';
+import { Ecosystem, VerdictRequestItem, Status, Action, BehaviorFinding, VerdictEnvelope } from '@inner/contracts';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface AlternativeSuggestion {
+    ecosystem: Ecosystem;
+    /** The package the agent asked about. */
+    requested: string;
+    /** Suggested safer package name, or null when nothing confident is known. */
+    suggestion: string | null;
+    /** Why this suggestion (or why none). */
+    rationale: string;
+    /** How the suggestion was derived. 'curated' = hand-picked map; 'none' = no match. */
+    source: 'curated' | 'none';
+}
+/**
+ * Suggest a safer alternative for a (usually blocked) package.
+ * Pure + synchronous so it can be unit-tested and reused by check_package.
+ */
+declare function suggestAlternative(ecosystem: Ecosystem, name: string): AlternativeSuggestion;
+
+interface ParseDepsInput {
+    /** Raw file contents (package.json / package-lock.json / requirements.txt). */
+    content?: string;
+    /** Hint for which parser to use; inferred from content when omitted. */
+    format?: 'package.json' | 'package-lock.json' | 'requirements.txt';
+    /** Ecosystem hint for ambiguous inputs (default inferred, fallback 'npm'). */
+    ecosystem?: Ecosystem;
+    /** Explicit package list (bypasses parsing). */
+    packages?: VerdictRequestItem[];
+}
+/** Back-compat: just the resolvable items (warnings dropped). */
+declare function parseDependencies(input: ParseDepsInput): VerdictRequestItem[];
+
+interface PackageVerdict {
+    ecosystem: Ecosystem;
+    name: string;
+    version: string;
+    /** True when the verdict never resolved (still PENDING after polling). */
+    pending: boolean;
+    status?: Status;
+    action: Action;
+    confidence?: number;
+    behaviors?: BehaviorFinding[];
+    policy_decision?: VerdictEnvelope['policy_decision'];
+    provisional?: boolean;
+    /** Present when the package is blocked/under-review. */
+    suggested_alternative?: AlternativeSuggestion;
+    /** Human-readable one-liner the agent can act on. */
+    summary: string;
+}
+interface CheckPackageArgs {
+    ecosystem: Ecosystem;
+    name: string;
+    version: string;
+}
+declare function checkPackage(client: VerdictClient, args: CheckPackageArgs): Promise<PackageVerdict>;
+interface CheckDependenciesArgs extends ParseDepsInput {
+}
+interface DependencyTally {
+    total: number;
+    allow: number;
+    review: number;
+    block: number;
+    pending: number;
+}
+interface CheckDependenciesResult {
+    tally: DependencyTally;
+    verdicts: PackageVerdict[];
+    /** True if any package is BLOCK/REVIEW or unresolved PENDING. */
+    has_risk: boolean;
+    /** Count of manifest entries skipped (unresolvable spec — NOT scanned). */
+    skipped: number;
+    /** One line per skipped entry, so the agent can surface what wasn't checked. */
+    warnings: string[];
+}
+declare function checkDependencies(client: VerdictClient, args: CheckDependenciesArgs): Promise<CheckDependenciesResult>;
+interface ExplainVerdictArgs {
+    ecosystem: Ecosystem;
+    name: string;
+    version: string;
+}
+interface VerdictExplanation {
+    ecosystem: Ecosystem;
+    name: string;
+    version: string;
+    pending: boolean;
+    status?: Status;
+    action?: Action;
+    confidence?: number;
+    corroboration?: VerdictEnvelope['corroboration'];
+    assurance?: VerdictEnvelope['assurance'];
+    provisional?: boolean;
+    /** Each behavior with its severity + the trace it cites. */
+    behaviors?: {
+        category: string;
+        severity: string;
+        evidence_ref: string;
+    }[];
+    capabilities?: VerdictEnvelope['capabilities'];
+    reasoning?: string;
+    evidence_uri?: string;
+    /** Narrative explanation the agent can show the user. */
+    explanation: string;
+}
+declare function explainVerdict(client: VerdictClient, args: ExplainVerdictArgs): Promise<VerdictExplanation>;
+interface SuggestAlternativeArgs {
+    ecosystem: Ecosystem;
+    name: string;
+}
+declare function suggestAlternativeHandler(args: SuggestAlternativeArgs): AlternativeSuggestion;
+interface ReviewRequest {
+    id: string;
+    ecosystem: Ecosystem;
+    name: string;
+    version?: string;
+    reason?: string;
+    requested_at: string;
+}
+interface RequestReviewArgs {
+    ecosystem: Ecosystem;
+    name: string;
+    version?: string;
+    reason?: string;
+}
+declare class ReviewStore {
+    private readonly reviews;
+    record(args: RequestReviewArgs): ReviewRequest;
+    list(): ReviewRequest[];
+}
+
+/** Build the MCP server with all 5 tools registered. Injectable client opts for tests. */
+declare function buildServer(clientOpts?: VerdictClientOptions): McpServer;
+
+export { type AlternativeSuggestion, type CheckDependenciesArgs, type CheckDependenciesResult, type CheckPackageArgs, type DependencyTally, type ExplainVerdictArgs, type PackageVerdict, type ParseDepsInput, type RequestReviewArgs, type ReviewRequest, ReviewStore, type SuggestAlternativeArgs, type VerdictExplanation, buildServer, checkDependencies, checkPackage, explainVerdict, parseDependencies, suggestAlternative, suggestAlternativeHandler };