@withpica/mcp-server
Version:
MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog
192 lines • 9.71 kB
JavaScript
// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
import { formatAsText, formatSuccess } from "@withpica/mcp-utils";
export class AnalyticsTools {
pica;
constructor(pica) {
this.pica = pica;
}
getTools() {
return [
// --- Carbon footprint ---
{
definition: {
name: "pica_carbon_footprint",
scope: "read:catalog",
audiences: ["stdio", "http", "public"],
tier: "read",
description: "Use when the user asks: 'what's my carbon footprint?', 'how sustainable is my catalog?', 'DIMPACT report', 'environmental impact', 'ESG metrics for sync pack'. " +
"Get the carbon footprint summary for your catalog (DIMPACT 2024 methodology — ~0.0128g CO2e per stream) — streaming, physical distribution, and production emissions.",
workflows: "infrastructure",
vernacular_kind: "creator-entry",
inputSchema: {
type: "object",
properties: {},
},
},
executor: this.carbonSummary.bind(this),
},
{
definition: {
name: "pica_carbon_live",
scope: "read:catalog",
audiences: ["stdio", "http", "public"],
tier: "read",
description: "Use when the user asks: 'show me live carbon metrics', 'what's my real-time streaming emissions?', 'live DIMPACT report'. " +
"Get live/real-time carbon metrics for ongoing streaming and distribution activity (DIMPACT 2024 methodology).",
workflows: "infrastructure",
vernacular_kind: "creator-entry",
inputSchema: {
type: "object",
properties: {},
},
},
executor: this.carbonLive.bind(this),
},
// --- Provenance ---
{
definition: {
name: "pica_provenance_stats",
scope: "read:catalog",
audiences: ["stdio", "http", "public"],
tier: "read",
description: "Get provenance statistics — how many works have chain-of-title records, " +
"attestation coverage, and verification status. " +
"For one work's full chain rather than catalog-wide counts, use pica_provenance_work.",
workflows: "infrastructure",
vernacular_kind: "specialist",
vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
inputSchema: {
type: "object",
properties: {},
},
},
executor: this.provenanceStats.bind(this),
},
{
definition: {
name: "pica_provenance_work",
scope: "read:catalog",
audiences: ["stdio", "http", "public"],
tier: "read",
description: "Get the full provenance chain for a specific work — " +
"creation history, ownership transfers, attestations, and verification entries. " +
"This reads the chain; for a downloadable chain-of-title document, use pica_provenance_certificate.",
workflows: "infrastructure",
vernacular_kind: "specialist",
vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
inputSchema: {
type: "object",
properties: {
work_id: {
type: "string",
description: "The work ID to get provenance for",
},
},
required: ["work_id"],
},
},
executor: this.provenanceWork.bind(this),
},
{
definition: {
name: "pica_provenance_certificate",
scope: "write:catalog",
audiences: ["stdio", "http", "public"],
tier: "write",
description: "Generate (or regenerate) a provenance certificate for a work — " +
"a downloadable chain-of-title document with attestation details. " +
"Each call writes a new certificate row; use pica_provenance_certificate_get " +
"to fetch the latest existing one without regenerating.",
workflows: "infrastructure",
vernacular_kind: "specialist",
vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
inputSchema: {
type: "object",
properties: {
work_id: {
type: "string",
description: "The work ID to generate a certificate for",
},
},
required: ["work_id"],
},
},
executor: this.provenanceCertificate.bind(this),
},
{
definition: {
name: "pica_provenance_certificate_get",
scope: "read:catalog",
audiences: ["stdio", "http", "public"],
tier: "read",
description: "Fetch an existing provenance certificate for a work without regenerating. " +
"Returns 404 NOT_FOUND if none has been generated yet — call pica_provenance_certificate first in that case.",
workflows: "infrastructure",
vernacular_kind: "specialist",
vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
inputSchema: {
type: "object",
properties: {
work_id: {
type: "string",
description: "The work ID to look up the certificate for",
},
},
required: ["work_id"],
},
},
executor: this.provenanceCertificateGet.bind(this),
},
// --- Catalog diligence ---
{
definition: {
name: "pica_catalog_diligence",
scope: "read:catalog",
audiences: ["stdio", "http", "public"],
tier: "read",
description: "Use when the user asks: 'am I ready to register?', 'can I submit X to MLC?', 'is X complete?'. " +
"Generate a technical due diligence report for the catalog — " +
"ownership clarity, registration coverage, identifier completeness, " +
"and readiness for lending, licensing, or acquisition. " +
"Prefer pica_catalog_health when the question is what to clean up first, not readiness.",
workflows: "infrastructure",
vernacular_kind: "creator-entry",
inputSchema: {
type: "object",
properties: {},
},
},
executor: this.catalogDiligence.bind(this),
},
];
}
async carbonSummary(_args) {
const result = await this.pica.analytics.carbonSummary();
return formatSuccess("Carbon footprint summary", result);
}
async carbonLive(_args) {
const result = await this.pica.analytics.carbonLive();
return formatSuccess("Live carbon metrics", result);
}
async provenanceStats(_args) {
const result = await this.pica.analytics.provenanceStats();
return formatAsText(result);
}
async provenanceWork(args) {
const result = await this.pica.analytics.provenanceWork(args.work_id);
return formatAsText(result);
}
async provenanceCertificate(args) {
const result = await this.pica.analytics.provenanceCertificate(args.work_id);
return formatSuccess(`Provenance certificate generated for work ${args.work_id}`, result);
}
async provenanceCertificateGet(args) {
const result = await this.pica.analytics.provenanceCertificateGet(args.work_id);
return formatSuccess(`Provenance certificate for work ${args.work_id}`, result);
}
async catalogDiligence(_args) {
const result = await this.pica.analytics.catalogDiligence();
return formatSuccess("Catalog diligence report", result);
}
}
//# sourceMappingURL=analytics.js.map