@cyanheads/wikidata-mcp-server 0.1.1

package/dist/config/server-config.js

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Server-specific configuration for wikidata-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+const ServerConfigSchema = z.object({
+    userAgent: z
+        .string()
+        .default('wikidata-mcp-server/0.1 (https://github.com/cyanheads/wikidata-mcp-server)')
+        .describe('User-Agent string for Wikimedia requests. Wikimedia policy requires a descriptive User-Agent.'),
+    sparqlTimeoutMs: z.coerce
+        .number()
+        .default(55_000)
+        .describe('Max time to wait for a SPARQL response in milliseconds. Default: 55000 (just under the 60s hard server limit).'),
+    restTimeoutMs: z.coerce
+        .number()
+        .default(10_000)
+        .describe('Max time to wait for REST API responses in milliseconds. Default: 10000.'),
+});
+let _config;
+/** Returns the lazy-parsed server configuration. */
+export function getServerConfig() {
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        userAgent: 'WIKIDATA_USER_AGENT',
+        sparqlTimeoutMs: 'WIKIDATA_SPARQL_TIMEOUT_MS',
+        restTimeoutMs: 'WIKIDATA_REST_TIMEOUT_MS',
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,OAAO,CAAC,4EAA4E,CAAC;SACrF,QAAQ,CACP,+FAA+F,CAChG;IACH,eAAe,EAAE,CAAC,CAAC,MAAM;SACtB,MAAM,EAAE;SACR,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CACP,gHAAgH,CACjH;IACH,aAAa,EAAE,CAAC,CAAC,MAAM;SACpB,MAAM,EAAE;SACR,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,0EAA0E,CAAC;CACxF,CAAC,CAAC;AAEH,IAAI,OAAuD,CAAC;AAE5D,oDAAoD;AACpD,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,SAAS,EAAE,qBAAqB;QAChC,eAAe,EAAE,4BAA4B;QAC7C,aAAa,EAAE,0BAA0B;KAC1C,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview wikidata-mcp-server MCP server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview wikidata-mcp-server MCP server entry point.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { wikidataEntityResource } from './mcp-server/resources/definitions/entity.resource.js';
+import { wikidataGetEntity } from './mcp-server/tools/definitions/get-entity.tool.js';
+import { wikidataGetLabels } from './mcp-server/tools/definitions/get-labels.tool.js';
+import { wikidataGetSitelinks } from './mcp-server/tools/definitions/get-sitelinks.tool.js';
+import { wikidataGetStatements } from './mcp-server/tools/definitions/get-statements.tool.js';
+import { wikidataResolveExternalId } from './mcp-server/tools/definitions/resolve-external-id.tool.js';
+import { wikidataSearchEntities } from './mcp-server/tools/definitions/search-entities.tool.js';
+import { wikidataSparqlQuery } from './mcp-server/tools/definitions/sparql-query.tool.js';
+import { initWikidataRestService } from './services/wikidata/wikidata-rest-service.js';
+import { initWikidataSparqlService } from './services/wikidata/wikidata-sparql-service.js';
+await createApp({
+    tools: [
+        wikidataSearchEntities,
+        wikidataGetEntity,
+        wikidataGetLabels,
+        wikidataGetStatements,
+        wikidataGetSitelinks,
+        wikidataSparqlQuery,
+        wikidataResolveExternalId,
+    ],
+    resources: [wikidataEntityResource],
+    prompts: [],
+    setup(core) {
+        initWikidataRestService(core.config, core.storage);
+        initWikidataSparqlService(core.config, core.storage);
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uDAAuD,CAAC;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAC;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,uDAAuD,CAAC;AAC9F,OAAO,EAAE,yBAAyB,EAAE,MAAM,4DAA4D,CAAC;AACvG,OAAO,EAAE,sBAAsB,EAAE,MAAM,wDAAwD,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,qDAAqD,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gDAAgD,CAAC;AAE3F,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,sBAAsB;QACtB,iBAAiB;QACjB,iBAAiB;QACjB,qBAAqB;QACrB,oBAAoB;QACpB,mBAAmB;QACnB,yBAAyB;KAC1B;IACD,SAAS,EAAE,CAAC,sBAAsB,CAAC;IACnC,OAAO,EAAE,EAAE;IACX,KAAK,CAAC,IAAI;QACR,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/entity.resource.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Wikidata entity resource — compact entity summary by QID or PID.
+ * @module mcp-server/resources/definitions/entity.resource
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const wikidataEntityResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    content: z.ZodString;
+}, z.core.$strip>, undefined>;
+//# sourceMappingURL=entity.resource.d.ts.map

package/dist/mcp-server/resources/definitions/entity.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AASrD,eAAO,MAAM,sBAAsB;;;;6BAsIjC,CAAC"}

package/dist/mcp-server/resources/definitions/entity.resource.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Wikidata entity resource — compact entity summary by QID or PID.
+ * @module mcp-server/resources/definitions/entity.resource
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { invalidParams, notFound } from '@cyanheads/mcp-ts-core/errors';
+import { getWikidataRestService, isPId, isQId, normalizeId, } from '../../../services/wikidata/wikidata-rest-service.js';
+export const wikidataEntityResource = resource('wikidata://entity/{id}', {
+    name: 'wikidata-entity',
+    description: 'Wikidata entity by QID or PID — labels (all languages), English description, ' +
+        'and a summary of key properties (instance-of P31, image P18, enwiki sitelink). ' +
+        'Formatted as compact markdown. For full entity data, use the wikidata_get_entity tool.',
+    mimeType: 'text/markdown',
+    params: z.object({
+        id: z.string().describe('Q-ID (e.g., "Q76") or P-ID (e.g., "P31") of the entity.'),
+    }),
+    output: z.object({
+        content: z.string().describe('Compact markdown summary of the entity.'),
+    }),
+    async handler(params, ctx) {
+        const id = normalizeId(params.id);
+        if (!isQId(id) && !isPId(id)) {
+            throw invalidParams(`"${params.id}" is not a valid Wikidata ID. Expected Q+digits (e.g., Q76) or P+digits (e.g., P31).`, { id: params.id });
+        }
+        const svc = getWikidataRestService();
+        ctx.log.info('Fetching entity resource', { id });
+        let entity;
+        try {
+            entity = await svc.fetchEntity(id, ctx);
+        }
+        catch (err) {
+            const e = err;
+            if (e?.data?.status === 404) {
+                throw notFound(`No Wikidata entity found for ID "${id}".`, { id }, { cause: err });
+            }
+            throw err;
+        }
+        const lines = [];
+        // Header: ID + English label
+        const enLabel = entity.labels?.en?.value;
+        lines.push(`# ${enLabel ? `${enLabel} (${id})` : id}`);
+        // English description
+        const enDesc = entity.descriptions?.en?.value;
+        if (enDesc)
+            lines.push(`*${enDesc}*`);
+        lines.push('');
+        // Type/data_type
+        if (entity.type === 'property' && entity.data_type) {
+            lines.push(`**Type:** Property | **Data type:** ${entity.data_type}`);
+        }
+        else {
+            lines.push(`**Type:** ${entity.type}`);
+        }
+        // Instance of (P31)
+        const instanceOf = entity.statements?.P31;
+        if (instanceOf?.length) {
+            const values = instanceOf
+                .slice(0, 3)
+                .map((stmt) => {
+                const content = stmt.value?.content;
+                return content?.id ?? '?';
+            })
+                .join(', ');
+            lines.push(`**Instance of:** ${values} *(resolve with wikidata_get_labels)*`);
+        }
+        // Wikipedia link (enwiki sitelink)
+        const enwiki = entity.sitelinks?.enwiki;
+        if (enwiki?.url) {
+            lines.push(`**Wikipedia:** [${enwiki.title}](${enwiki.url})`);
+        }
+        else if (enwiki?.title) {
+            lines.push(`**Wikipedia:** ${enwiki.title}`);
+        }
+        // Image (P18)
+        const images = entity.statements?.P18;
+        if (images?.length) {
+            const firstImage = images[0];
+            const imgContent = firstImage?.value?.content;
+            if (typeof imgContent === 'string' && imgContent) {
+                lines.push(`**Image:** ${imgContent}`);
+            }
+        }
+        // Labels summary
+        const labelCount = entity.labels ? Object.keys(entity.labels).length : 0;
+        if (labelCount > 0) {
+            lines.push('');
+            lines.push(`**Labels available:** ${labelCount} languages`);
+            const sample = Object.entries(entity.labels ?? {})
+                .slice(0, 5)
+                .map(([lang, lb]) => `${lang}: ${lb.value}`)
+                .join(' | ');
+            if (sample)
+                lines.push(sample);
+        }
+        // Statement count
+        const propCount = entity.statements ? Object.keys(entity.statements).length : 0;
+        if (propCount > 0) {
+            lines.push(`**Statements:** ${propCount} properties`);
+        }
+        lines.push('');
+        lines.push(`**Wikidata URL:** https://www.wikidata.org/wiki/${id}`);
+        return { content: lines.join('\n') };
+    },
+    list: () => ({
+        resources: [
+            {
+                uri: 'wikidata://entity/Q76',
+                name: 'Barack Obama (Q76)',
+                description: 'Example: Wikidata entity for Barack Obama',
+                mimeType: 'text/markdown',
+            },
+            {
+                uri: 'wikidata://entity/Q42',
+                name: 'Douglas Adams (Q42)',
+                description: 'Example: Wikidata entity for Douglas Adams',
+                mimeType: 'text/markdown',
+            },
+            {
+                uri: 'wikidata://entity/P31',
+                name: 'instance of (P31)',
+                description: 'Example: Wikidata property "instance of"',
+                mimeType: 'text/markdown',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=entity.resource.js.map

package/dist/mcp-server/resources/definitions/entity.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity.resource.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-entity.tool.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Fetch a Wikidata entity by QID or PID with field selection.
+ * @module mcp-server/tools/definitions/get-entity.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const wikidataGetEntity: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    id: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        labels: "labels";
+        descriptions: "descriptions";
+        aliases: "aliases";
+        statements: "statements";
+        sitelinks: "sitelinks";
+    }>>>;
+    languages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    data_type: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    descriptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    statements: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{}, z.core.$loose>>>>;
+    sitelinks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{}, z.core.$loose>>>;
+    fieldsReturned: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "entity_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No entity exists at this ID — the REST API returned resource-not-found.";
+    readonly recovery: "Verify the ID with wikidata_search_entities or check the Wikidata URL directly.";
+}, {
+    readonly reason: "invalid_id";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "ID format is not recognized as a Q-ID or P-ID.";
+    readonly recovery: "Supply a valid Q-ID (Q followed by digits, e.g. Q76) or P-ID (P followed by digits, e.g. P31).";
+}]>;
+//# sourceMappingURL=get-entity.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-entity.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAUjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmQ5B,CAAC"}

package/dist/mcp-server/tools/definitions/get-entity.tool.js

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Fetch a Wikidata entity by QID or PID with field selection.
+ * @module mcp-server/tools/definitions/get-entity.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getWikidataRestService, isPId, isQId, normalizeId, } from '../../../services/wikidata/wikidata-rest-service.js';
+const FIELD_ENUM = z.enum(['labels', 'descriptions', 'aliases', 'statements', 'sitelinks']);
+export const wikidataGetEntity = tool('wikidata_get_entity', {
+    title: 'Get Wikidata Entity',
+    description: 'Fetch a Wikidata entity (item or property) by QID or PID. ' +
+        'The REST API always returns the full entity payload (300KB+ for major items like Q76 Barack Obama). ' +
+        'Use the fields parameter to trim what is returned to the caller — the network cost is fixed, ' +
+        'but the context budget benefit is real. Omit fields to get all data. ' +
+        'Q-IDs (e.g. Q76) fetch items; P-IDs (e.g. P31) fetch properties from the correct endpoint automatically. ' +
+        'Use wikidata_get_statements for deep claim traversal with label resolution.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        id: z
+            .string()
+            .min(1)
+            .describe('Q-ID (e.g., "Q76") or P-ID (e.g., "P31"). Case-insensitive — normalized to uppercase.'),
+        fields: z
+            .array(FIELD_ENUM)
+            .optional()
+            .describe('Fields to include in the response. Options: "labels", "descriptions", "aliases", "statements", "sitelinks". ' +
+            'Omit for all fields. Filtering is client-side — the full entity is always fetched from the API.'),
+        languages: z
+            .array(z.string())
+            .optional()
+            .describe('Language codes to include in labels, descriptions, and aliases (e.g., ["en", "de"]). ' +
+            'Omit to return all available languages.'),
+    }),
+    output: z.object({
+        id: z.string().describe('Normalized entity ID (e.g., "Q76" or "P31").'),
+        type: z.string().describe('Entity type: "item" or "property".'),
+        data_type: z
+            .string()
+            .optional()
+            .describe('Property data type (e.g., "wikibase-item", "external-id"). Present on properties only.'),
+        labels: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Map of language code to label string (e.g., {"en": "Barack Obama", "de": "Barack Obama"}).'),
+        descriptions: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Map of language code to description string (e.g., {"en": "44th President of the United States"}).'),
+        aliases: z
+            .record(z.string(), z.array(z.string()))
+            .optional()
+            .describe('Map of language code to list of alias strings (e.g., {"en": ["Barack H. Obama", "President Obama"]}).'),
+        statements: z
+            .record(z.string(), z.array(z.object({}).passthrough()))
+            .optional()
+            .describe('Map of property ID to array of raw statement objects. Use wikidata_get_statements for resolved claims with label resolution.'),
+        // Sitelink values are from a dynamic external API — passthrough preserves all nested fields
+        // (title, url, badges) in structuredContent without aspirational per-field typing.
+        sitelinks: z
+            .record(z.string(), z.object({}).passthrough())
+            .optional()
+            .describe('Map of site code (e.g., "enwiki") to sitelink metadata with title, url, and badges fields.'),
+        fieldsReturned: z.array(z.string()).describe('Which fields are included in this response.'),
+    }),
+    errors: [
+        {
+            reason: 'entity_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No entity exists at this ID — the REST API returned resource-not-found.',
+            recovery: 'Verify the ID with wikidata_search_entities or check the Wikidata URL directly.',
+        },
+        {
+            reason: 'invalid_id',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'ID format is not recognized as a Q-ID or P-ID.',
+            recovery: 'Supply a valid Q-ID (Q followed by digits, e.g. Q76) or P-ID (P followed by digits, e.g. P31).',
+        },
+    ],
+    async handler(input, ctx) {
+        const id = normalizeId(input.id);
+        if (!isQId(id) && !isPId(id)) {
+            throw ctx.fail('invalid_id', `"${input.id}" is not a valid Wikidata ID. Expected Q+digits (item) or P+digits (property).`, { ...ctx.recoveryFor('invalid_id') });
+        }
+        const svc = getWikidataRestService();
+        ctx.log.info('Fetching Wikidata entity', {
+            id,
+            fields: input.fields,
+            languages: input.languages,
+        });
+        let entity;
+        try {
+            entity = await svc.fetchEntity(id, ctx);
+        }
+        catch (err) {
+            if (err?.data?.status === 404) {
+                throw ctx.fail('entity_not_found', `No entity found for ID "${id}".`, {
+                    ...ctx.recoveryFor('entity_not_found'),
+                });
+            }
+            throw err;
+        }
+        // Determine which fields to include
+        const requestedFields = new Set(input.fields ?? ['labels', 'descriptions', 'aliases', 'statements', 'sitelinks']);
+        // Helper to filter language-keyed maps
+        const filterLangs = (map) => {
+            if (!map)
+                return;
+            if (!input.languages?.length)
+                return map;
+            const langSet = new Set(input.languages);
+            const filtered = Object.fromEntries(Object.entries(map).filter(([lang]) => langSet.has(lang)));
+            return Object.keys(filtered).length ? filtered : undefined;
+        };
+        // Flatten label/description maps from { language, value } → string
+        const flattenLabelMap = (map) => {
+            if (!map)
+                return;
+            return Object.fromEntries(Object.entries(map).map(([lang, entry]) => [lang, entry.value]));
+        };
+        const flattenAliasMap = (map) => {
+            if (!map)
+                return;
+            return Object.fromEntries(Object.entries(map).map(([lang, entries]) => [lang, entries.map((e) => e.value)]));
+        };
+        const result = {
+            id: entity.id,
+            type: entity.type,
+            fieldsReturned: [...requestedFields],
+        };
+        if (entity.data_type)
+            result.data_type = entity.data_type;
+        if (requestedFields.has('labels')) {
+            const labels = flattenLabelMap(filterLangs(entity.labels));
+            if (labels)
+                result.labels = labels;
+        }
+        if (requestedFields.has('descriptions')) {
+            const descriptions = flattenLabelMap(filterLangs(entity.descriptions));
+            if (descriptions)
+                result.descriptions = descriptions;
+        }
+        if (requestedFields.has('aliases')) {
+            const aliases = flattenAliasMap(filterLangs(entity.aliases));
+            if (aliases)
+                result.aliases = aliases;
+        }
+        if (requestedFields.has('statements') && entity.statements) {
+            result.statements = entity.statements;
+        }
+        if (requestedFields.has('sitelinks') && entity.sitelinks) {
+            result.sitelinks = Object.fromEntries(Object.entries(entity.sitelinks).map(([site, sl]) => [
+                site,
+                {
+                    title: sl.title,
+                    ...(sl.url ? { url: sl.url } : {}),
+                    ...(sl.badges?.length ? { badges: sl.badges } : {}),
+                },
+            ]));
+        }
+        // The output schema defines the full shape — result satisfies it at runtime
+        // even though the TypeScript type is widened to Record<string, unknown>.
+        return result;
+    },
+    format: (result) => {
+        const lines = [`## ${result.id} (${result.type})`];
+        if (result.data_type)
+            lines.push(`**Data type:** ${result.data_type}`);
+        lines.push(`**Fields returned:** ${result.fieldsReturned.join(', ')}`);
+        if (result.labels) {
+            const enLabel = result.labels.en;
+            const allLabels = Object.entries(result.labels)
+                .slice(0, 5)
+                .map(([lang, val]) => `${lang}: ${val}`)
+                .join(', ');
+            lines.push(`**Label:** ${enLabel ?? Object.values(result.labels)[0] ?? '(none)'}`);
+            if (Object.keys(result.labels).length > 1) {
+                lines.push(`**Labels (sample):** ${allLabels}${Object.keys(result.labels).length > 5 ? ` … (${Object.keys(result.labels).length} total)` : ''}`);
+            }
+        }
+        if (result.descriptions) {
+            const enDesc = result.descriptions.en;
+            if (enDesc) {
+                lines.push(`**Description:** ${enDesc}`);
+            }
+            const otherDescs = Object.entries(result.descriptions)
+                .filter(([lang]) => lang !== 'en')
+                .slice(0, 3)
+                .map(([lang, val]) => `${lang}: ${val}`);
+            if (otherDescs.length)
+                lines.push(`**Descriptions (sample):** ${otherDescs.join(' | ')}`);
+        }
+        if (result.aliases) {
+            const allAliasEntries = Object.entries(result.aliases).slice(0, 3);
+            for (const [lang, aliases] of allAliasEntries) {
+                if (aliases.length) {
+                    lines.push(`**Aliases (${lang}):** ${aliases.slice(0, 5).join(', ')}${aliases.length > 5 ? ` … (${aliases.length} total)` : ''}`);
+                }
+            }
+        }
+        if (result.statements) {
+            const propCount = Object.keys(result.statements).length;
+            const claimCount = Object.values(result.statements).reduce((acc, stmts) => acc + stmts.length, 0);
+            lines.push(`**Statements:** ${propCount} properties, ${claimCount} total claims`);
+        }
+        if (result.sitelinks) {
+            const sitelinkCount = Object.keys(result.sitelinks).length;
+            const enwiki = result.sitelinks.enwiki;
+            lines.push(`**Sitelinks:** ${sitelinkCount} total`);
+            if (enwiki)
+                lines.push(`**Wikipedia (en):** ${enwiki.url ?? enwiki.title}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-entity.tool.js.map

package/dist/mcp-server/tools/definitions/get-entity.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-entity.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-entity.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-labels.tool.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Batch-resolve QIDs/PIDs to human-readable labels and descriptions.
+ * @module mcp-server/tools/definitions/get-labels.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const wikidataGetLabels: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    ids: z.ZodArray<z.ZodString>;
+    languages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    entities: z.ZodRecord<z.ZodString, z.ZodObject<{
+        labels: z.ZodRecord<z.ZodString, z.ZodString>;
+        descriptions: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    found: z.ZodNumber;
+    notFound: z.ZodArray<z.ZodString>;
+    languages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "invalid_ids";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "One or more IDs in the array are not valid Q-IDs or P-IDs.";
+    readonly recovery: "All IDs must match Q+digits or P+digits format (e.g., Q76, P31). Use wikidata_search_entities to find valid IDs.";
+}]>;
+//# sourceMappingURL=get-labels.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-labels.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-labels.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-labels.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;GA8G5B,CAAC"}

package/dist/mcp-server/tools/definitions/get-labels.tool.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Batch-resolve QIDs/PIDs to human-readable labels and descriptions.
+ * @module mcp-server/tools/definitions/get-labels.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getWikidataRestService, normalizeId } from '../../../services/wikidata/wikidata-rest-service.js';
+export const wikidataGetLabels = tool('wikidata_get_labels', {
+    title: 'Get Wikidata Labels',
+    description: 'Resolve one or more QIDs or PIDs to their human-readable labels and descriptions. ' +
+        'Lightweight — returns no claim data. Supports up to 50 IDs per call (batched automatically). ' +
+        'Designed for the common agent pattern: receive QIDs from a SPARQL query, then humanize them. ' +
+        'Uses the MediaWiki wbgetentities API for efficient batch resolution.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    input: z.object({
+        ids: z
+            .array(z.string().min(1))
+            .min(1)
+            .max(50)
+            .describe('Q-IDs (e.g., "Q76") or P-IDs (e.g., "P31") to resolve. 1–50 IDs per call.'),
+        languages: z
+            .array(z.string().min(1))
+            .min(1)
+            .default(['en'])
+            .describe('BCP 47 language codes for returned labels and descriptions (e.g., ["en", "de", "fr"]).'),
+    }),
+    output: z.object({
+        entities: z
+            .record(z.string(), z.object({
+            labels: z
+                .record(z.string(), z.string())
+                .describe('Map of language code to label string. Keys match the requested languages that have data.'),
+            descriptions: z
+                .record(z.string(), z.string())
+                .describe('Map of language code to description string. Keys match the requested languages that have data.'),
+        }))
+            .describe('Map of entity ID to labels and descriptions. IDs that were not found are absent.'),
+        found: z.number().describe('Count of IDs that returned data.'),
+        notFound: z
+            .array(z.string())
+            .describe('IDs from the request that did not return data (not found or invalid).'),
+        languages: z.array(z.string()).describe('The language codes that were requested.'),
+    }),
+    errors: [
+        {
+            reason: 'invalid_ids',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'One or more IDs in the array are not valid Q-IDs or P-IDs.',
+            recovery: 'All IDs must match Q+digits or P+digits format (e.g., Q76, P31). Use wikidata_search_entities to find valid IDs.',
+        },
+    ],
+    async handler(input, ctx) {
+        // Validate all IDs
+        const normalized = input.ids.map(normalizeId);
+        const invalid = normalized.filter((id) => !/^[QP]\d+$/.test(id));
+        if (invalid.length > 0) {
+            throw ctx.fail('invalid_ids', `Invalid Wikidata IDs: ${invalid.join(', ')}. IDs must be Q+digits or P+digits.`, { invalid, ...ctx.recoveryFor('invalid_ids') });
+        }
+        const svc = getWikidataRestService();
+        ctx.log.info('Resolving labels', { count: normalized.length, languages: input.languages });
+        const labelData = await svc.fetchLabels(normalized, input.languages, ctx);
+        const notFound = normalized.filter((id) => !labelData[id]);
+        return {
+            entities: labelData,
+            found: Object.keys(labelData).length,
+            notFound,
+            languages: input.languages,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**Languages:** ${result.languages.join(', ')} | **Found:** ${result.found}`,
+        ];
+        if (result.notFound.length > 0) {
+            lines.push(`**Not found:** ${result.notFound.join(', ')}`);
+        }
+        lines.push('');
+        for (const [id, data] of Object.entries(result.entities)) {
+            const enLabel = data.labels.en ?? Object.values(data.labels)[0] ?? id;
+            const enDesc = data.descriptions.en ?? Object.values(data.descriptions)[0] ?? '';
+            lines.push(`**${id}:** ${enLabel}${enDesc ? ` — ${enDesc}` : ''}`);
+            // Show additional language labels if requested
+            const otherLangs = Object.entries(data.labels)
+                .filter(([lang]) => lang !== 'en')
+                .map(([lang, lbl]) => `${lang}: ${lbl}`)
+                .slice(0, 3);
+            if (otherLangs.length)
+                lines.push(`  ${otherLangs.join(' | ')}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-labels.tool.js.map