@takuhon/core 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -3801,6 +3801,115 @@ interface CvDocument {
  */
 declare function deriveCv(localized: LocalizedTakuhon): CvDocument;
 
+/**
+ * MCP (Model Context Protocol) projection of a profile.
+ *
+ * This module describes how a takuhon profile is exposed to an AI agent as a
+ * set of read-only MCP tools and resources, and how each one is answered from a
+ * profile document — *without* committing to a transport (stdio / HTTP) or to
+ * any MCP SDK.
+ *
+ * The split mirrors the rest of core: deciding *what* to expose and *what it
+ * returns* is a pure, deterministic projection over the canonical document
+ * (exactly like {@link generateJsonLd}), so it lives here in `@takuhon/core` and
+ * stays runtime-free (spec §2.3). The transport, JSON-RPC framing, and server
+ * lifecycle are runtime-aware; they live in `@takuhon/mcp` and the CLI /
+ * Cloudflare adapters, which call the pure executors below.
+ *
+ * Everything here is read-only. No tool or resource touches the admin surface,
+ * and every answer passes through {@link applyPublicPrivacyFilter}, so an MCP
+ * client sees exactly what `GET /api/profile`, `GET /api/jsonld`, `GET
+ * /api/schema`, and `GET /takuhon.json` already expose — no more.
+ *
+ * The catalog ({@link MCP_TOOLS} / {@link MCP_RESOURCES}) is plain data with no
+ * SDK dependency, so the `@takuhon/mcp` wiring can register it against the
+ * official `@modelcontextprotocol/sdk` and later be swapped to a hand-rolled
+ * dispatcher without touching this file.
+ */
+
+/**
+ * Profile sections a `get_section` call may request: the content-bearing keys
+ * of a locale-resolved profile (the spec §6 data sections). `settings`,
+ * `meta`, `schemaVersion`, and `resolvedLocale` are intentionally excluded —
+ * they are configuration / bookkeeping, not profile content an agent reads.
+ */
+declare const MCP_PROFILE_SECTIONS: readonly ["profile", "links", "careers", "projects", "skills", "certifications", "memberships", "volunteering", "honors", "education", "publications", "languages", "courses", "patents", "testScores", "recommendations", "contact"];
+/** One of the {@link MCP_PROFILE_SECTIONS} a `get_section` call accepts. */
+type McpProfileSection = (typeof MCP_PROFILE_SECTIONS)[number];
+/** A JSON Schema (draft 2020-12) object describing a tool's input arguments. */
+type McpInputSchema = Readonly<Record<string, unknown>>;
+/** A read-only MCP tool definition — plain data, no SDK dependency. */
+interface McpToolDefinition {
+    /** Stable tool id used in `tools/call`. */
+    name: string;
+    /** Human-readable title for display. */
+    title: string;
+    /** What the tool returns; shown to the agent when it chooses a tool. */
+    description: string;
+    /** JSON Schema for the tool's `arguments` object. */
+    inputSchema: McpInputSchema;
+}
+/** A read-only MCP resource definition — plain data, no SDK dependency. */
+interface McpResourceDefinition {
+    /** Stable resource URI used in `resources/read`. */
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    /** MIME type of the resource contents. */
+    mimeType: string;
+}
+/** Result of {@link executeMcpTool}: the structured value the tool produced. */
+interface McpToolResult {
+    /**
+     * The JSON value the tool produced — already normalized, locale-resolved, and
+     * privacy-filtered. The transport layer serializes this to MCP wire content.
+     */
+    data: unknown;
+    /** Locale the result was resolved at, when the tool resolved one. */
+    resolvedLocale?: string;
+}
+/** Result of {@link readMcpResource}: one resource's contents. */
+interface McpResourceResult {
+    uri: string;
+    mimeType: string;
+    /** The JSON value of the resource. The transport layer serializes it. */
+    data: unknown;
+}
+/**
+ * Thrown by {@link executeMcpTool} / {@link readMcpResource} for an unknown
+ * tool/resource name or invalid arguments. The transport layer maps it to the
+ * appropriate MCP error (a JSON-RPC error for a malformed request, or an
+ * `isError` tool result for a bad argument) — core stays transport-agnostic.
+ */
+declare class McpRequestError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The read-only tools an MCP client may call against the profile. */
+declare const MCP_TOOLS: readonly McpToolDefinition[];
+/** The read-only resources an MCP client may read. */
+declare const MCP_RESOURCES: readonly McpResourceDefinition[];
+/**
+ * Execute a read-only MCP tool against a profile document.
+ *
+ * `profile` is the raw validated {@link Takuhon} (the transport layer loaded it
+ * from KV / a file). Locale-aware tools normalize, locale-resolve, and
+ * privacy-filter it exactly as `GET /api/profile` does, then project the
+ * requested view. Pure and deterministic — no clock, no randomness, no I/O.
+ *
+ * @throws {McpRequestError} for an unknown tool name or invalid arguments.
+ */
+declare function executeMcpTool(name: string, args: Readonly<Record<string, unknown>>, profile: Takuhon): McpToolResult;
+/**
+ * Read a read-only MCP resource from a profile document. Pure and
+ * deterministic.
+ *
+ * @throws {McpRequestError} for an unknown resource URI.
+ */
+declare function readMcpResource(uri: string, profile: Takuhon): McpResourceResult;
+
 /**
  * Image-asset helpers for uploaded media (avatars, project images): magic-byte
  * type detection, header-only dimension / frame reading, and metadata stripping
@@ -3901,4 +4010,4 @@ declare function stripImageMetadata(bytes: Uint8Array, mime: AcceptedImageMime):
  */
 declare const SCHEMA_VERSION = "0.5.0";
 
-export { ACCEPTED_IMAGE_MIME_TYPES, type AcceptedImageMime, type ActivitySettings, type ActivitySnapshot, type ActivityStorage, type Address, type AssetOptions, type AssetRecord, type Avatar, type Career, type Certification, type CodingTime, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type ContributionCalendar, type ContributionDay, type Course, type CvDocument, type CvHeader, type CvSection, type CvSectionKind, type Education, type ExportOptions, type ExportedTakuhon, type Honor, IMAGE_EXTENSIONS, type ImageInfo, ImportError, type Iso3166Alpha2, type IsoDateTime, type Language, type LanguageBreakdown, type LanguageProficiency, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedCertification, type LocalizedCourse, type LocalizedEducation, type LocalizedHonor, type LocalizedLanguage, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedMembership, type LocalizedPatent, type LocalizedProfile, type LocalizedProject, type LocalizedPublication, type LocalizedRecommendation, type LocalizedRecommendationAuthor, type LocalizedTakuhon, type LocalizedTestScore, type LocalizedTitle, type LocalizedVolunteering, MAX_IMAGE_BYTES, MAX_IMAGE_DIMENSION, MAX_IMAGE_FRAMES, type Membership, type Meta, type MetaPrivacy, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Patent, type PatentStatus, type Profile, type Project, type Publication, RANK_FULL_CODING_HOURS, RANK_FULL_CONTRIBUTIONS, RANK_TIER_THRESHOLDS, type RankInput, type RankTier, type RankTierLabel, type Recommendation, type RecommendationAuthor, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type TestScore, type ValidationError, type ValidationResult, type Volunteering, type YearMonth, applyPublicPrivacyFilter, computeLanguagePercentages, deriveCv, deriveRankTier, detectImageMime, exportTakuhon, formatCodingTime, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, importTakuhon, isActivitySnapshot, migrateTakuhon, migrations, normalize, readImageInfo, renderActivitySvg, resolveLocale, schema, stripImageMetadata, validate };
+export { ACCEPTED_IMAGE_MIME_TYPES, type AcceptedImageMime, type ActivitySettings, type ActivitySnapshot, type ActivityStorage, type Address, type AssetOptions, type AssetRecord, type Avatar, type Career, type Certification, type CodingTime, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type ContributionCalendar, type ContributionDay, type Course, type CvDocument, type CvHeader, type CvSection, type CvSectionKind, type Education, type ExportOptions, type ExportedTakuhon, type Honor, IMAGE_EXTENSIONS, type ImageInfo, ImportError, type Iso3166Alpha2, type IsoDateTime, type Language, type LanguageBreakdown, type LanguageProficiency, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedCertification, type LocalizedCourse, type LocalizedEducation, type LocalizedHonor, type LocalizedLanguage, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedMembership, type LocalizedPatent, type LocalizedProfile, type LocalizedProject, type LocalizedPublication, type LocalizedRecommendation, type LocalizedRecommendationAuthor, type LocalizedTakuhon, type LocalizedTestScore, type LocalizedTitle, type LocalizedVolunteering, MAX_IMAGE_BYTES, MAX_IMAGE_DIMENSION, MAX_IMAGE_FRAMES, MCP_PROFILE_SECTIONS, MCP_RESOURCES, MCP_TOOLS, type McpInputSchema, type McpProfileSection, McpRequestError, type McpResourceDefinition, type McpResourceResult, type McpToolDefinition, type McpToolResult, type Membership, type Meta, type MetaPrivacy, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Patent, type PatentStatus, type Profile, type Project, type Publication, RANK_FULL_CODING_HOURS, RANK_FULL_CONTRIBUTIONS, RANK_TIER_THRESHOLDS, type RankInput, type RankTier, type RankTierLabel, type Recommendation, type RecommendationAuthor, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type TestScore, type ValidationError, type ValidationResult, type Volunteering, type YearMonth, applyPublicPrivacyFilter, computeLanguagePercentages, deriveCv, deriveRankTier, detectImageMime, executeMcpTool, exportTakuhon, formatCodingTime, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, importTakuhon, isActivitySnapshot, migrateTakuhon, migrations, normalize, readImageInfo, readMcpResource, renderActivitySvg, resolveLocale, schema, stripImageMetadata, validate };

package/dist/index.js

@@ -11587,6 +11587,161 @@ function deriveCv(localized) {
   };
 }
 
+// src/mcp.ts
+var MCP_PROFILE_SECTIONS = [
+  "profile",
+  "links",
+  "careers",
+  "projects",
+  "skills",
+  "certifications",
+  "memberships",
+  "volunteering",
+  "honors",
+  "education",
+  "publications",
+  "languages",
+  "courses",
+  "patents",
+  "testScores",
+  "recommendations",
+  "contact"
+];
+var McpRequestError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "McpRequestError";
+  }
+};
+var LANG_PROPERTY = {
+  type: "string",
+  description: 'BCP-47 locale tag (e.g. "ja", "en"). Resolves to the requested locale, falling back to the profile default when omitted or unavailable.'
+};
+var MCP_TOOLS = [
+  {
+    name: "get_profile",
+    title: "Get profile",
+    description: "Return the owner's full public profile, resolved to one locale and privacy-filtered (identical to the public `GET /api/profile`).",
+    inputSchema: {
+      type: "object",
+      properties: { lang: LANG_PROPERTY },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "get_section",
+    title: "Get profile section",
+    description: "Return a single section of the public profile (e.g. careers, education, skills), resolved to one locale and privacy-filtered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        section: {
+          type: "string",
+          enum: [...MCP_PROFILE_SECTIONS],
+          description: "Which profile section to return."
+        },
+        lang: LANG_PROPERTY
+      },
+      required: ["section"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "get_jsonld",
+    title: "Get JSON-LD",
+    description: "Return the Schema.org JSON-LD (a `ProfilePage` wrapping a `Person`) for the profile, resolved to one locale (identical to `GET /api/jsonld`).",
+    inputSchema: {
+      type: "object",
+      properties: { lang: LANG_PROPERTY },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_locales",
+    title: "List locales",
+    description: "List the locales this profile is available in, plus the default \u2014 useful before calling another tool with a `lang` argument.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  }
+];
+var MCP_RESOURCES = [
+  {
+    uri: "takuhon://profile",
+    name: "profile",
+    title: "Canonical profile (takuhon.json)",
+    description: "The full canonical takuhon.json, privacy-filtered, with every locale retained (identical to `GET /takuhon.json`).",
+    mimeType: "application/json"
+  },
+  {
+    uri: "takuhon://schema",
+    name: "schema",
+    title: "Takuhon JSON Schema",
+    description: "The public JSON Schema contract the profile conforms to (identical to `GET /api/schema`). Lets an agent understand the document shape.",
+    mimeType: "application/json"
+  }
+];
+function executeMcpTool(name, args, profile) {
+  switch (name) {
+    case "get_profile": {
+      const localized = publicView(profile, readLang(args));
+      return { data: localized, resolvedLocale: localized.resolvedLocale };
+    }
+    case "get_section": {
+      const section = readSection(args);
+      const localized = publicView(profile, readLang(args));
+      return { data: localized[section], resolvedLocale: localized.resolvedLocale };
+    }
+    case "get_jsonld": {
+      const localized = publicView(profile, readLang(args));
+      return { data: generateJsonLd(localized), resolvedLocale: localized.resolvedLocale };
+    }
+    case "list_locales":
+      return {
+        data: {
+          defaultLocale: profile.settings.defaultLocale,
+          availableLocales: profile.settings.availableLocales,
+          ...profile.settings.fallbackLocale !== void 0 ? { fallbackLocale: profile.settings.fallbackLocale } : {}
+        }
+      };
+    default:
+      throw new McpRequestError(`Unknown MCP tool: ${name}`);
+  }
+}
+function readMcpResource(uri, profile) {
+  switch (uri) {
+    case "takuhon://profile":
+      return {
+        uri,
+        mimeType: "application/json",
+        data: applyPublicPrivacyFilter(profile)
+      };
+    case "takuhon://schema":
+      return { uri, mimeType: "application/json", data: schema };
+    default:
+      throw new McpRequestError(`Unknown MCP resource: ${uri}`);
+  }
+}
+function publicView(profile, lang) {
+  return applyPublicPrivacyFilter(resolveLocale(normalize(profile), lang));
+}
+function readLang(args) {
+  const lang = args.lang;
+  if (lang === void 0) return void 0;
+  if (typeof lang !== "string") {
+    throw new McpRequestError("`lang` must be a string (a BCP-47 locale tag).");
+  }
+  return lang;
+}
+function readSection(args) {
+  const section = args.section;
+  if (typeof section !== "string" || !isProfileSection(section)) {
+    throw new McpRequestError(`\`section\` must be one of: ${MCP_PROFILE_SECTIONS.join(", ")}.`);
+  }
+  return section;
+}
+function isProfileSection(value) {
+  return MCP_PROFILE_SECTIONS.includes(value);
+}
+
 // src/image.ts
 var ACCEPTED_IMAGE_MIME_TYPES = [
   "image/jpeg",
@@ -11927,6 +12082,10 @@ export {
   MAX_IMAGE_BYTES,
   MAX_IMAGE_DIMENSION,
   MAX_IMAGE_FRAMES,
+  MCP_PROFILE_SECTIONS,
+  MCP_RESOURCES,
+  MCP_TOOLS,
+  McpRequestError,
   MigrationError,
   NotFoundError,
   RANK_FULL_CODING_HOURS,
@@ -11940,6 +12099,7 @@ export {
   deriveCv,
   deriveRankTier,
   detectImageMime,
+  executeMcpTool,
   exportTakuhon,
   formatCodingTime,
   generateJsonLd,
@@ -11951,6 +12111,7 @@ export {
   migrations,
   normalize,
   readImageInfo,
+  readMcpResource,
   renderActivitySvg,
   resolveLocale,
   schema,