promptspeak-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# PromptSpeak MCP Server
+
+Pre-execution governance layer for AI agents, implemented as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server.
+
+**What it does:** Intercepts every agent tool call before execution, validates against deterministic rules, and blocks or holds risky operations for human approval — in under 0.12ms.
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Test
+
+```bash
+npm test          # 951 tests
+npm run test:stress  # Concurrent load tests
+```
+
+## Run
+
+```bash
+npm start         # Start MCP server via stdio
+```
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "promptspeak": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/server.js"]
+    }
+  }
+}
+```
+
+## Validation Pipeline
+
+Every tool call passes through 5 stages:
+
+1. **Circuit Breaker** — Halted agents blocked immediately (no further checks)
+2. **Frame Validation** — Structural, semantic, and chain rule checks
+3. **Drift Detection** — Behavioral anomaly detection against baseline
+4. **Hold Manager** — Risky operations held for human approval
+5. **Interceptor** — Final permission gate
+
+If any stage fails, the tool call is blocked before execution.
+
+## MCP Tools (25+)
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| Governance | `ps_validate`, `ps_execute`, `ps_execute_dry_run` | Core validation and execution |
+| Holds | `ps_hold_list`, `ps_hold_approve`, `ps_hold_reject` | Human-in-the-loop approvals |
+| State | `ps_state_halt`, `ps_state_resume`, `ps_drift_history` | Agent lifecycle control |
+| Config | `ps_config_set`, `ps_config_get`, `ps_feature_set` | Runtime configuration |
+| Symbols | `ps_symbol_create`, `ps_symbol_get`, `ps_symbol_list` | Entity registry |
+| Audit | `ps_audit_get` | Compliance audit trail |
+
+## Architecture
+
+```
+src/
+├── gatekeeper/       # 5-stage validation pipeline
+├── drift/            # Circuit breaker, tripwire, baseline monitoring
+├── symbols/          # SQLite-backed entity registry
+├── policies/         # Policy file loader + overlay system
+├── operator/         # Operator configuration
+├── translation/      # Natural language ↔ symbolic frame translation
+├── legal/            # Citation verification
+├── multi_agent/      # Commander's Intent coordination
+├── swarm/            # Market operation coordination
+├── recon/            # Intelligence processing
+├── tools/            # MCP tool implementations
+├── handlers/         # Tool dispatch + metadata registry
+└── core/             # Logging, errors, result patterns
+```
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Validation latency | 0.103ms avg (P95: 0.121ms) |
+| Operations/second | 6,977 |
+| Holds/second | 33,333 |
+| Test coverage | 951 tests, 30 test files |
+
+## Requirements
+
+- Node.js ≥ 20.0.0
+- TypeScript 5.3+
+
+## License
+
+Copyright 2025-2026 ERP Access, Inc. All rights reserved.

package/dist/agents/database.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Multi-Agent Data Intelligence Framework (MADIF) - Database Layer
+ *
+ * SQLite database operations for campaigns, agents, data sources, and proposals.
+ * Follows the pattern established in src/symbols/database.ts
+ */
+import Database from 'better-sqlite3';
+import type { AcquisitionCampaign, AgentDefinition, AgentInstance, AgentProposal, DataSourceSpec, AgentStatus, CampaignStatus } from './types.js';
+/**
+ * Initialize the agent database with all required tables.
+ */
+export declare function initializeAgentDatabase(dbPath?: string): Database.Database;
+/**
+ * Get the database instance.
+ */
+export declare function getAgentDatabase(): Database.Database;
+/**
+ * Close the database connection.
+ */
+export declare function closeAgentDatabase(): void;
+/**
+ * Create a new acquisition campaign.
+ */
+export declare function createCampaign(campaign: Omit<AcquisitionCampaign, 'id'>): AcquisitionCampaign;
+/**
+ * Get a campaign by ID.
+ */
+export declare function getCampaign(campaignId: string): AcquisitionCampaign | null;
+/**
+ * Update campaign status and metrics.
+ */
+export declare function updateCampaign(campaignId: string, updates: Partial<AcquisitionCampaign>): boolean;
+/**
+ * List campaigns with optional filters.
+ */
+export declare function listCampaigns(filters?: {
+    status?: CampaignStatus;
+    topic?: string;
+    limit?: number;
+    offset?: number;
+}): AcquisitionCampaign[];
+/**
+ * Register a new agent definition.
+ */
+export declare function createAgentDefinition(definition: AgentDefinition): AgentDefinition;
+/**
+ * Get an agent definition by ID.
+ */
+export declare function getAgentDefinition(agentId: string): AgentDefinition | null;
+/**
+ * List agent definitions with optional filters.
+ */
+export declare function listAgentDefinitions(filters?: {
+    category?: string;
+    riskLevel?: string;
+    limit?: number;
+}): AgentDefinition[];
+/**
+ * Create a new agent instance.
+ */
+export declare function createAgentInstance(instance: AgentInstance): AgentInstance;
+/**
+ * Get an agent instance by ID.
+ */
+export declare function getAgentInstance(instanceId: string): AgentInstance | null;
+/**
+ * Update agent instance status and metrics.
+ */
+export declare function updateAgentInstance(instanceId: string, updates: Partial<AgentInstance>): boolean;
+/**
+ * List agent instances with optional filters.
+ */
+export declare function listAgentInstances(filters?: {
+    campaignId?: string;
+    definitionId?: string;
+    status?: AgentStatus;
+    limit?: number;
+}): AgentInstance[];
+/**
+ * Register a new data source.
+ */
+export declare function createDataSource(source: DataSourceSpec & {
+    sourceId: string;
+    symbolId?: string;
+    discoveredBy?: string;
+    qualityScore?: number;
+    validationStatus?: string;
+}): void;
+/**
+ * Get a data source by ID.
+ */
+export declare function getDataSource(sourceId: string): (DataSourceSpec & {
+    sourceId: string;
+}) | null;
+/**
+ * Update data source usage statistics.
+ */
+export declare function updateDataSourceUsage(sourceId: string, symbolsExtracted: number): boolean;
+/**
+ * Record an audit event.
+ */
+export declare function recordAgentAuditEvent(event: {
+    eventType: string;
+    agentId?: string;
+    instanceId?: string;
+    campaignId?: string;
+    proposalId?: string;
+    operatorId?: string;
+    details?: Record<string, unknown>;
+}): string;
+/**
+ * Query audit log.
+ */
+export declare function queryAgentAuditLog(filters: {
+    eventType?: string;
+    agentId?: string;
+    instanceId?: string;
+    campaignId?: string;
+    since?: string;
+    limit?: number;
+}): Array<{
+    eventId: string;
+    eventType: string;
+    agentId?: string;
+    instanceId?: string;
+    campaignId?: string;
+    proposalId?: string;
+    operatorId?: string;
+    timestamp: string;
+    details: Record<string, unknown>;
+}>;
+/**
+ * Create a new proposal in the database.
+ */
+export declare function createProposal(proposal: AgentProposal): void;
+/**
+ * Get a proposal by ID.
+ */
+export declare function getProposal(proposalId: string): AgentProposal | null;
+/**
+ * Get a proposal by hold ID.
+ */
+export declare function getProposalByHoldId(holdId: string): AgentProposal | null;
+/**
+ * Update proposal state and optionally set approval/rejection details.
+ */
+export declare function updateProposalState(proposalId: string, state: AgentProposal['state'], options?: {
+    approvedBy?: string;
+    approvedAt?: string;
+    rejectionReason?: string;
+    holdId?: string;
+    decision?: AgentProposal['decision'];
+}): boolean;
+/**
+ * List pending proposals.
+ */
+export declare function listPendingProposals(): AgentProposal[];
+/**
+ * List proposals with optional filters.
+ */
+export declare function listProposals(filters?: {
+    state?: AgentProposal['state'];
+    campaignId?: string;
+    limit?: number;
+}): AgentProposal[];
+/**
+ * Delete expired proposals and return the count of deleted proposals.
+ */
+export declare function deleteExpiredProposals(): number;
+/**
+ * Load all active proposals (pending, approved but not yet completed).
+ */
+export declare function loadAllProposals(): AgentProposal[];
+//# sourceMappingURL=database.d.ts.map

package/dist/agents/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/agents/database.ts"],"names":[],"mappings":"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"}