@tpsdev-ai/flair-mcp 0.52.0 → 0.54.1

package/dist/skills.d.ts

@@ -0,0 +1,50 @@
+/**
+ * skills.ts — stdio-adapter shaping for skill_* tools (flair#1575).
+ *
+ * Native `/mcp` implements skill_store / skill_search / skill_get as thin
+ * wrappers over Memory / SemanticSearch (resources/mcp-tools.ts). This
+ * package talks HTTP via FlairClient, so the wrappers here only shape
+ * the request body and the client-visible result — they re-implement no
+ * write, recall, or scoping logic. Server-side SkillScan, forced
+ * durability=persistent, and resolveReadScope still run on the daemon.
+ *
+ * Progressive disclosure matches the native contract: skill_search returns
+ * catalog cards (never `content` / embedding); skill_get is the disclosure
+ * step for the full procedure. skill_get always strips embedding /
+ * embeddingModel (flair#1579) — there is no includeEmbedding opt-in.
+ */
+/** The tag that marks a Memory as a skill (resources/skill-write.ts). */
+export declare const SKILL_TAG = "skill";
+export declare function isSkillRecord(record: unknown): boolean;
+/**
+ * Lightweight skill CATALOG card — id/name/trigger/description/tags/agentId.
+ * `name`/`description` live in the opaque metadata JSON blob; a corrupt or
+ * absent blob simply yields no name/desc. `content` and the raw embedding
+ * are deliberately absent (skill_search progressive-disclosure contract).
+ */
+export declare function projectSkillCard(r: unknown): Record<string, unknown>;
+export declare function stripInternalMemoryFields<T extends Record<string, unknown>>(value: T): T;
+/** Body for PUT /Memory/:id — matches native skill_store's Memory.post() shape. */
+export declare function buildSkillStoreBody(opts: {
+    agentId: string;
+    content: string;
+    trigger?: string;
+    name?: string;
+    description?: string;
+    tags?: string[];
+    claimedClient?: string;
+}): {
+    id: string;
+    body: Record<string, unknown>;
+};
+/** SemanticSearch body for skill_search — no agentId (scope is the signed identity). */
+export declare function buildSkillSearchBody(opts: {
+    task: string;
+    limit?: number;
+}): Record<string, unknown>;
+/**
+ * Project a SemanticSearch response onto catalog cards. A guard/error payload
+ * (no `results` array) is returned untouched so the caller can surface it.
+ */
+export declare function projectSkillSearchResponse(res: unknown): unknown;
+export declare function formatSkillCatalog(results: Array<Record<string, unknown>>): string;

package/dist/skills.js

@@ -0,0 +1,120 @@
+/**
+ * skills.ts — stdio-adapter shaping for skill_* tools (flair#1575).
+ *
+ * Native `/mcp` implements skill_store / skill_search / skill_get as thin
+ * wrappers over Memory / SemanticSearch (resources/mcp-tools.ts). This
+ * package talks HTTP via FlairClient, so the wrappers here only shape
+ * the request body and the client-visible result — they re-implement no
+ * write, recall, or scoping logic. Server-side SkillScan, forced
+ * durability=persistent, and resolveReadScope still run on the daemon.
+ *
+ * Progressive disclosure matches the native contract: skill_search returns
+ * catalog cards (never `content` / embedding); skill_get is the disclosure
+ * step for the full procedure. skill_get always strips embedding /
+ * embeddingModel (flair#1579) — there is no includeEmbedding opt-in.
+ */
+/** The tag that marks a Memory as a skill (resources/skill-write.ts). */
+export const SKILL_TAG = "skill";
+const INTERNAL_MEMORY_FIELDS = ["embedding", "embeddingModel"];
+export function isSkillRecord(record) {
+    const tags = record?.tags;
+    return Array.isArray(tags) && tags.includes(SKILL_TAG);
+}
+/**
+ * Lightweight skill CATALOG card — id/name/trigger/description/tags/agentId.
+ * `name`/`description` live in the opaque metadata JSON blob; a corrupt or
+ * absent blob simply yields no name/desc. `content` and the raw embedding
+ * are deliberately absent (skill_search progressive-disclosure contract).
+ */
+export function projectSkillCard(r) {
+    const row = (r ?? {});
+    let name;
+    let description;
+    if (typeof row.metadata === "string" && row.metadata.length > 0) {
+        try {
+            const meta = JSON.parse(row.metadata);
+            if (meta && typeof meta === "object") {
+                if (typeof meta.name === "string")
+                    name = meta.name;
+                if (typeof meta.description === "string")
+                    description = meta.description;
+            }
+        }
+        catch {
+            /* opaque/corrupt metadata → no name/description on the card */
+        }
+    }
+    return {
+        id: row.id,
+        name,
+        trigger: row.trigger,
+        description,
+        tags: row.tags,
+        agentId: row.agentId,
+    };
+}
+export function stripInternalMemoryFields(value) {
+    const out = { ...value };
+    for (const field of INTERNAL_MEMORY_FIELDS)
+        delete out[field];
+    return out;
+}
+/** Body for PUT /Memory/:id — matches native skill_store's Memory.post() shape. */
+export function buildSkillStoreBody(opts) {
+    const id = `${opts.agentId}-${crypto.randomUUID()}`;
+    const body = {
+        id,
+        agentId: opts.agentId,
+        content: opts.content,
+        tags: [SKILL_TAG, ...(Array.isArray(opts.tags) ? opts.tags : [])],
+    };
+    // durability is NOT set — the server forces persistent for skill-tagged
+    // writes and rejects an explicit ephemeral/session.
+    if (typeof opts.trigger === "string" && opts.trigger.length > 0)
+        body.trigger = opts.trigger;
+    if (opts.claimedClient)
+        body.claimedClient = opts.claimedClient;
+    const meta = {};
+    if (typeof opts.name === "string" && opts.name.length > 0)
+        meta.name = opts.name;
+    if (typeof opts.description === "string" && opts.description.length > 0)
+        meta.description = opts.description;
+    if (Object.keys(meta).length > 0)
+        body.metadata = JSON.stringify(meta);
+    return { id, body };
+}
+/** SemanticSearch body for skill_search — no agentId (scope is the signed identity). */
+export function buildSkillSearchBody(opts) {
+    return {
+        q: opts.task,
+        tag: SKILL_TAG,
+        limit: opts.limit ?? 5,
+        includeMetadata: true,
+        includeTrigger: true,
+    };
+}
+/**
+ * Project a SemanticSearch response onto catalog cards. A guard/error payload
+ * (no `results` array) is returned untouched so the caller can surface it.
+ */
+export function projectSkillSearchResponse(res) {
+    if (!res || typeof res !== "object" || !Array.isArray(res.results)) {
+        return res;
+    }
+    const payload = res;
+    return { ...payload, results: payload.results.map(projectSkillCard) };
+}
+export function formatSkillCatalog(results) {
+    if (results.length === 0)
+        return "No matching skills found.";
+    return results
+        .map((card, i) => {
+        const title = typeof card.name === "string" && card.name.length > 0 ? card.name : "(unnamed skill)";
+        const trigger = typeof card.trigger === "string" && card.trigger.length > 0 ? card.trigger : "";
+        const desc = typeof card.description === "string" && card.description.length > 0 ? card.description : "";
+        const idStr = card.id ? `id:${card.id}` : "";
+        const header = [title, trigger, idStr].filter(Boolean).join(" — ");
+        return desc ? `${i + 1}. ${header}\n   ${desc}` : `${i + 1}. ${header}`;
+    })
+        .join("\n");
+}

package/node_modules/@tpsdev-ai/flair-tool-descriptors/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   Copyright 2026 TPS Dev AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/node_modules/@tpsdev-ai/flair-tool-descriptors/README.md

@@ -0,0 +1,22 @@
+# @tpsdev-ai/flair-tool-descriptors
+
+Transport-agnostic MCP tool descriptors for [Flair](https://tps.dev/#flair).
+
+This package is **pure data and types**: tool name, description, JSON Schema
+`inputSchema`, output shape, and reviewed surface flags. It imports neither
+Harper nor FlairClient. The Flair server binds each native descriptor to its
+Harper implementation; `@tpsdev-ai/flair-mcp` binds each stdio descriptor to a
+FlairClient HTTP call. Both tool sets are derived from this list, so a new
+descriptor appears on every listed surface with zero hand-wiring (flair#1580).
+
+## Install
+
+```bash
+npm install @tpsdev-ai/flair-tool-descriptors
+```
+
+## Surfaces
+
+`native` and `stdio` default to true. Set either to `false` for a reviewed
+one-sided tool (`attention` is native-only; `relationship_store` is
+stdio-only). The #1578 exemption list is derived from those flags.

package/node_modules/@tpsdev-ai/flair-tool-descriptors/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Transport-agnostic MCP tool descriptors (flair#1580).
+ *
+ * Pure data + types: name, description, inputSchema, output shape, and
+ * reviewed surface flags. No Harper, no FlairClient, no Zod, no HTTP.
+ *
+ * The server TOOLS registry binds each native descriptor to its Harper impl.
+ * The flair-mcp stdio adapter binds each stdio descriptor to a FlairClient
+ * call. Both tool sets are DERIVED from this list — a new descriptor appears
+ * on every surface that lists it, with zero hand-wiring.
+ */
+/** JSON Schema object used as MCP tools/list inputSchema. */
+export interface JsonSchemaObject {
+    type: "object";
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+export interface JsonSchemaProperty {
+    type?: string;
+    description?: string;
+    enum?: string[];
+    items?: {
+        type?: string;
+    };
+    default?: unknown;
+}
+/** MCP tool descriptor as returned by tools/list. */
+export interface McpToolDef {
+    name: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    annotations?: Record<string, unknown>;
+}
+/**
+ * One MCP-facing tool. `native` / `stdio` default true — omit both and the
+ * tool appears on every surface. Set false for a reviewed one-sided tool
+ * (the #1578 exemption list is derived from these flags).
+ */
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    /** One-line output shape (MCP metadata). Native conformance contracts pin this as `summary`. */
+    outputShape: string;
+    annotations?: Record<string, unknown>;
+    /** When false, native /mcp does not bind this tool. Default true. */
+    native?: boolean;
+    /** When false, the stdio adapter does not bind this tool. Default true. */
+    stdio?: boolean;
+    /** Stdio-only description when the HTTP path differs from native /mcp policy. */
+    stdioDescription?: string;
+    /** Properties advertised on native /mcp only (reviewed, e.g. flair#1579). */
+    stdioOmitProperties?: readonly string[];
+    /** Properties advertised on the stdio adapter only (reviewed). */
+    stdioExtraProperties?: Record<string, JsonSchemaProperty>;
+}
+export declare function isNativeTool(d: ToolDescriptor): boolean;
+export declare function isStdioTool(d: ToolDescriptor): boolean;
+export declare function toMcpToolDef(d: ToolDescriptor): McpToolDef;
+/** Native tools/list def, minus reviewed stdio-only omissions. */
+export declare function toStdioMcpToolDef(d: ToolDescriptor): McpToolDef;
+export declare function descriptorNames(descriptors: readonly ToolDescriptor[]): string[];
+export declare const TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+export declare const NATIVE_TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+export declare const STDIO_TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+/** Derived #1578 exemption list — one-sided by construction, not hand-synced. */
+export declare const SURFACE_EXEMPTIONS: {
+    readonly registryOnly: string[];
+    readonly adapterOnly: string[];
+};