@mogintel/mcp-pk-shared

Shared Pakistan-Stack library: error taxonomy, token codec, canonical types, idempotency store, health-check helpers, and shared CI workflow templates. Consumed by every @mogintel/mcp-* provider MCP and by mogintel/nokar. Not an MCP server — no tools registered here.

Install

npm install @mogintel/mcp-pk-shared

Quick start

import { issueApprovalToken, verifyApprovalToken, idempotencyKey, TTL_CONFIG } from '@mogintel/mcp-pk-shared';

const scope = { install_id: 'inst_1', tool_name: 'mcp-jazzcash.create_payment_link', caller_identity: 'agent:runtime' };
const params = { amount: 500, currency: 'PKR', order_ref: 'ORD-1' };

// ttlSeconds defaults to the canonical TTL_CONFIG (600s) — no consumer defines a local TTL const.
const issued = issueApprovalToken({ scope, params, secret: process.env.HMAC_SECRET!, ttlSeconds: TTL_CONFIG });
const result = verifyApprovalToken(issued.token, process.env.HMAC_SECRET!, { expectedScope: scope, params });
// result: { valid: true, payload } | { valid: false, reason: 'TOKEN_SIGNATURE_INVALID' | 'TOKEN_EXPIRED' | ... }

const key = idempotencyKey('order', 'create', params.order_ref, params); // stable, drift-sensitive

See examples/quick-start.ts for the runnable version.

Tool surface

Shared library — no tools. See @mogintel/mcp-jazzcash, @mogintel/mcp-easypaisa, @mogintel/mcp-tcs-courier, @mogintel/mcp-daraz-seller for provider tools.

Auth setup

Not applicable — this package holds no auth code of its own. Provider MCPs load credentials via the Doppler nokar-prod-<provider> scope; see each provider MCP's README.

Error semantics

Errors are data across the MCP boundary — never thrown (AD-10). src/errors.ts ships the canonical PakStackError taxonomy; each member (AMOUNT_EXCEEDS_TIER, TOKEN_EXPIRED, TOKEN_SCOPE_MISMATCH, TOKEN_PARAMS_MISMATCH, RATE_LIMITED, UPSTREAM_ERROR, IDEMPOTENCY_CONFLICT, …) carries { code, retryable, httpStatus } and serialises via .toWire() to the snake_case wire union { ok: false, error: { code, message, retryable, http_status, upstream_ref? } }. The convenience field is httpStatus (camel); the wire field is http_status (snake).

Tier model

See mogintel/nokar/ARCHITECTURE-SPINE.md §AD-3 — every MCP tool declares T1_READ | T2_WRITE_CONFIRM | T3_HUMAN_ONLY in its manifest.json; the facade enforces the tier at call time, not the MCP.

Rate limits

Not applicable — this is a client-side library.

Sandbox vs prod toggle

Not applicable — no runtime.

CONTRIBUTING

Auth-critical paths (src/tokens.ts, src/errors.ts, src/auth.ts, scripts/workflow-templates/**, scripts/forbidden-calls.txt) require code-owner review from @mogintel/security + @yahya. See .github/CODEOWNERS.

Licence (MIT)

See LICENSE.

Commercial CTA

Unaffiliated community wrapper around public APIs. Commercial support and hosted operator console available via MogIntel — contact [email protected].