@clawpify/skills 1.0.1

package/src/auth.ts

@@ -0,0 +1,109 @@
+/**
+ * Shopify OAuth Client Credentials
+ * For apps installed on stores you own (server-to-server)
+ */
+
+export interface AccessTokenResponse {
+  accessToken: string;
+  scope: string;
+  expiresIn: number;
+}
+
+export interface ClientCredentialsConfig {
+  storeUrl: string;
+  clientId: string;
+  clientSecret: string;
+}
+
+/**
+ * Get an access token using the Client Credentials grant.
+ * Token expires in 24 hours and must be refreshed with the same request.
+ *
+ * @see https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
+ */
+export async function getAccessToken(
+  config: ClientCredentialsConfig
+): Promise<AccessTokenResponse> {
+  const storeUrl = config.storeUrl
+    .replace(/^https?:\/\//, "")
+    .replace(/\/$/, "");
+
+  const response = await fetch(
+    `https://${storeUrl}/admin/oauth/access_token`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+      }),
+    }
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`OAuth error (${response.status}): ${text}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    scope: string;
+    expires_in: number;
+  };
+
+  return {
+    accessToken: data.access_token,
+    scope: data.scope,
+    expiresIn: data.expires_in,
+  };
+}
+
+/**
+ * Create a Shopify client config from environment variables.
+ * Supports two authentication methods:
+ * 1. Direct access token (SHOPIFY_ACCESS_TOKEN) - uses token directly
+ * 2. Client credentials (SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET) - fetches token via OAuth
+ */
+export async function createAuthenticatedConfig(): Promise<{
+  storeUrl: string;
+  accessToken: string;
+  scope?: string;
+  expiresIn?: number;
+}> {
+  const storeUrl = process.env.SHOPIFY_STORE_URL;
+  const directToken = process.env.SHOPIFY_ACCESS_TOKEN;
+  const clientId = process.env.SHOPIFY_CLIENT_ID;
+  const clientSecret = process.env.SHOPIFY_CLIENT_SECRET;
+
+  if (!storeUrl) {
+    throw new Error("Missing required environment variable: SHOPIFY_STORE_URL");
+  }
+
+  // Option 1: Use direct access token if provided
+  if (directToken) {
+    return {
+      storeUrl,
+      accessToken: directToken,
+    };
+  }
+
+  // Option 2: Use client credentials OAuth flow
+  if (clientId && clientSecret) {
+    const token = await getAccessToken({ storeUrl, clientId, clientSecret });
+    return {
+      storeUrl,
+      accessToken: token.accessToken,
+      scope: token.scope,
+      expiresIn: token.expiresIn,
+    };
+  }
+
+  throw new Error(
+    "Missing authentication credentials. Provide either:\n" +
+      "  - SHOPIFY_ACCESS_TOKEN (direct token), or\n" +
+      "  - SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET (OAuth client credentials)"
+  );
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Clawpify - Shopify Agent SDK
+ *
+ * Query and manage Shopify stores via GraphQL Admin API with AI agents.
+ *
+ * @example
+ * ```ts
+ * import { ShopifyClient } from "clawpify";
+ *
+ * const client = new ShopifyClient({
+ *   storeUrl: "my-store.myshopify.com",
+ *   accessToken: "shpat_xxxxx",
+ * });
+ *
+ * const { data } = await client.graphql(`{
+ *   products(first: 5) {
+ *     nodes { id title }
+ *   }
+ * }`);
+ * ```
+ *
+ * @example Using the AI agent (requires @anthropic-ai/sdk)
+ * ```ts
+ * import { ShopifyClient } from "clawpify";
+ * import { ShopifyAgent } from "clawpify/agent";
+ * import { loadSkills } from "clawpify/skills";
+ *
+ * const client = new ShopifyClient({ storeUrl, accessToken });
+ * const skills = await loadSkills();
+ * const agent = new ShopifyAgent({ shopify: client, skillContent: skills });
+ *
+ * const result = await agent.chat("List my products");
+ * console.log(result.response);
+ * ```
+ */
+
+// Core client
+export { ShopifyClient, createShopifyClient } from "./shopify";
+
+// Authentication
+export {
+  createAuthenticatedConfig,
+  getAccessToken,
+  type AccessTokenResponse,
+  type ClientCredentialsConfig,
+} from "./auth";
+
+// AI Agent (requires @anthropic-ai/sdk peer dependency)
+export { ShopifyAgent } from "./agent";
+
+// Skills loader
+export { loadSkills } from "./skills";
+
+// Re-export types for convenience
+export type { ShopifyClientConfig, GraphQLResponse } from "./shopify";

package/src/mcp-server.ts

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createAuthenticatedConfig } from "./auth.js";
+import { ShopifyClient } from "./shopify.js";
+import { readdir, readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillsDir = join(__dirname, "..", "clawpify");
+
+// Load .env from ~/.clawpify/.env if it exists (for MCP server mode)
+const configDir = join(homedir(), ".clawpify");
+const envPath = join(configDir, ".env");
+try {
+  if (existsSync(envPath)) {
+    const envContent = await readFile(envPath, "utf-8");
+    for (const line of envContent.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#")) {
+        const [key, ...valueParts] = trimmed.split("=");
+        const value = valueParts.join("=");
+        if (key && value && !process.env[key]) {
+          process.env[key] = value;
+        }
+      }
+    }
+    console.error(`Loaded config from ${envPath}`);
+  }
+} catch {
+  // Ignore errors, will use env vars from MCP config or current .env
+}
+
+// Cache the authenticated client
+let shopifyClient: ShopifyClient | null = null;
+
+async function getShopifyClient(): Promise<ShopifyClient> {
+  if (!shopifyClient) {
+    const config = await createAuthenticatedConfig();
+    shopifyClient = new ShopifyClient({
+      storeUrl: config.storeUrl,
+      accessToken: config.accessToken,
+    });
+  }
+  return shopifyClient;
+}
+
+// Create MCP server
+const server = new Server(
+  {
+    name: "clawpify",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "shopify_graphql",
+      description:
+        "Execute GraphQL queries against Shopify Admin API. Use this to query products, orders, customers, inventory, and manage store data.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "GraphQL query or mutation",
+          },
+          variables: {
+            type: "object",
+            description: "GraphQL variables (optional)",
+          },
+        },
+        required: ["query"],
+      },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "shopify_graphql") {
+    const { query, variables } = request.params.arguments as {
+      query: string;
+      variables?: Record<string, any>;
+    };
+
+    try {
+      const client = await getShopifyClient();
+      const result = await client.graphql(query, variables);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  throw new Error(`Unknown tool: ${request.params.name}`);
+});
+
+// List available resources (skill files)
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  try {
+    const files = await readdir(skillsDir);
+    const resources = files
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => ({
+        uri: `shopify://skills/${f.replace(".md", "")}`,
+        name: f.replace(".md", ""),
+        mimeType: "text/markdown",
+        description: `Shopify ${f.replace(".md", "")} skill documentation`,
+      }));
+
+    return { resources };
+  } catch {
+    return { resources: [] };
+  }
+});
+
+// Read resource content
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
+  const match = uri.match(/^shopify:\/\/skills\/(.+)$/);
+
+  if (!match) {
+    throw new Error(`Invalid resource URI: ${uri}`);
+  }
+
+  const filename = `${match[1]}.md`;
+  const filepath = join(skillsDir, filename);
+
+  try {
+    const content = await readFile(filepath, "utf-8");
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: content,
+        },
+      ],
+    };
+  } catch {
+    throw new Error(`Failed to read resource: ${filename}`);
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Clawpify MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/shopify.ts

@@ -0,0 +1,63 @@
+export interface ShopifyClientConfig {
+  /** Shopify store URL (e.g. "my-store.myshopify.com") */
+  storeUrl: string;
+  /** Admin API access token */
+  accessToken: string;
+  /** API version (defaults to "2026-01") */
+  apiVersion?: string;
+}
+
+export interface GraphQLResponse<T = any> {
+  data?: T;
+  errors?: Array<{ message: string; locations?: Array<{ line: number; column: number }> }>;
+  extensions?: Record<string, any>;
+}
+
+export class ShopifyClient {
+  private storeUrl: string;
+  private accessToken: string;
+  private apiVersion: string;
+
+  constructor(config: ShopifyClientConfig) {
+    this.storeUrl = config.storeUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+    this.accessToken = config.accessToken;
+    this.apiVersion = config.apiVersion ?? "2026-01";
+  }
+
+  /** Execute a GraphQL query or mutation against the Shopify Admin API */
+  async graphql<T = any>(
+    query: string,
+    variables?: Record<string, any>
+  ): Promise<GraphQLResponse<T>> {
+    const url = `https://${this.storeUrl}/admin/api/${this.apiVersion}/graphql.json`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Shopify-Access-Token": this.accessToken,
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Shopify API error (${response.status}): ${text}`);
+    }
+
+    return response.json() as Promise<GraphQLResponse<T>>;
+  }
+}
+
+export function createShopifyClient() {
+  const storeUrl = process.env.SHOPIFY_STORE_URL;
+  const accessToken = process.env.SHOPIFY_ACCESS_TOKEN;
+
+  if (!storeUrl || !accessToken) {
+    throw new Error(
+      "Missing required environment variables: SHOPIFY_STORE_URL and SHOPIFY_ACCESS_TOKEN"
+    );
+  }
+
+  return new ShopifyClient({ storeUrl, accessToken });
+}

package/src/skills.ts

@@ -0,0 +1,42 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Load all skill files from the clawpify skills directory.
+ * Works both locally and when installed as an npm package.
+ *
+ * Optionally provide a custom directory path to load skills from.
+ */
+export async function loadSkills(customDir?: string): Promise<string> {
+  const baseDir =
+    customDir ??
+    join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+
+  const skillParts: string[] = [];
+  await collectMarkdown(baseDir, skillParts);
+
+  return skillParts.join("\n\n---\n\n");
+}
+
+async function collectMarkdown(
+  dir: string,
+  parts: string[]
+): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectMarkdown(fullPath, parts);
+    } else if (entry.name.endsWith(".md")) {
+      const content = await readFile(fullPath, "utf-8");
+      parts.push(content);
+    }
+  }
+}