@linkyourskill/mcp-client

@linkyourskill/mcp-client

Official TypeScript / Node.js SDK for the LinkYourSkill agent API. Search Skillanbieter (service providers), prepare orders for agentowner approval, and track order status — from any AI agent or backend.

This is a thin, typed wrapper over the public REST agent API (/api/agent/*). It has zero runtime dependencies (uses the global fetch, Node 18+).

Install

npm install @linkyourskill/mcp-client

Quick start

import { createClient } from '@linkyourskill/mcp-client';

const lys = createClient({
  token: process.env.LYS_TOKEN!,
  // url: 'http://localhost'  // optional — defaults to https://app.linkyourskill.ai
});

// Search for providers
const providers = await lys.searchSkillanbieter({
  query: 'Klempner',
  service_area: 'Berlin',
});

// Create an order (sent to the agentowner for WhatsApp approval)
const order = await lys.prepareOrder({
  title: 'Wasserhahn reparieren',
  description: 'Tropfender Wasserhahn in der Küche',
  location: 'Berlin Mitte',
  timeframe: 'Nächste Woche',
  price_range_min: 50,
  price_range_max: 120,
});

// Track status
const status = await lys.getOrderStatus({ order_id: order.id });
console.log(status.status); // e.g. "pending_approval"

Authentication

Every call is authenticated with a bearer token (lys_…). Mint one in the agentowner dashboard, or use the read-only demo token from the API docs. The SDK sends it as Authorization: Bearer <token>.

Configuration

createClient(options):

Option	Type	Default	Description
token	string	— (required)	Agent API token.
url	string	https://app.linkyourskill.ai	API origin. The SDK appends /api/agent/*. Point at http://localhost for a local stack.
fetch	typeof fetch	global fetch	Custom fetch (testing / non-standard runtimes).

API reference

Method	Maps to	Description
searchSkillanbieter(params?)	GET /api/agent/skillanbieter/search	Search providers by query, category, area, rating, availability, geo.
getSkillanbieterRatings({ skillanbieter_id, page?, limit? })	GET …/skillanbieter/:id/ratings	Ratings & reviews for one provider.
prepareOrder(params)	POST /api/agent/orders	Create an order for agentowner approval.
listOrders({ status?, page?, limit? })	GET /api/agent/orders	List this agent's orders.
listActiveOrders()	GET /api/agent/orders?status=…	Only non-terminal orders.
getOrder({ order_id })	GET /api/agent/orders/:id	Full order incl. event timeline.
getOrderStatus({ order_id })	derived from GET …/orders/:id	Condensed status + last event + transition path.
getOrderEvents({ order_id })	derived from GET …/orders/:id	Raw event timeline.
getProfile()	GET /api/agent/profile	This token's agent profile and scopes.

Error handling

Any non-2xx response throws a LysApiError:

import { LysApiError } from '@linkyourskill/mcp-client';

try {
  await lys.prepareOrder({ /* … */ });
} catch (err) {
  if (err instanceof LysApiError) {
    console.error(err.status, err.code, err.message); // e.g. 400 "validation_error" "title is required"
  }
}

MCP transport

Prefer raw Model Context Protocol? The same capabilities are exposed as 18 MCP tools at POST /mcp. This SDK targets the REST surface so methods return plain typed objects; use the MCP endpoint directly when you want tool-calling from an MCP-native agent.

Development

npm install
npm run build      # tsc → dist/
npm test           # vitest unit tests (mocked fetch)
npm run typecheck

End-to-end coverage against a live stack lives in the root Playwright suite (tests/e2e/sdk-client.spec.ts).

Releasing

Publishing is automated. Create a GitHub Release tagged sdk-v<version> and CI (.github/workflows/publish-sdk.yml) builds, tests, and publishes that version to npm via Trusted Publishing (OIDC) with provenance — no token needed, no local npm version bump required:

gh release create sdk-v0.1.1 --title "mcp-client 0.1.1" --generate-notes

License

MIT LinkYourSkill