@lpm-registry/mcp-server 0.1.0

package/lib/server.js

@@ -0,0 +1,357 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { z } from "zod"
+import { getBaseUrl, getToken } from "./auth.js"
+import { MemoryCache } from "./cache.js"
+import { add } from "./tools/add.js"
+import { apiDocs } from "./tools/api-docs.js"
+import { browseSource } from "./tools/browse-source.js"
+import { getInstallCommand } from "./tools/get-install-command.js"
+import { install } from "./tools/install.js"
+import { llmContext } from "./tools/llm-context.js"
+import { packageContext } from "./tools/package-context.js"
+import { packageInfo } from "./tools/package-info.js"
+import { packageSkills } from "./tools/package-skills.js"
+import { packagesByOwner } from "./tools/packages-by-owner.js"
+import { poolStats } from "./tools/pool-stats.js"
+import { qualityReport } from "./tools/quality-report.js"
+import { search } from "./tools/search.js"
+import { searchOwners } from "./tools/search-owners.js"
+import { userInfo } from "./tools/user-info.js"
+
+/**
+ * Create and configure the MCP server with all LPM tools.
+ * @returns {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer}
+ */
+export function createServer() {
+	const server = new McpServer({
+		name: "lpm-registry",
+		version: "0.1.0",
+	})
+
+	const cache = new MemoryCache()
+	const context = { cache, getToken, getBaseUrl }
+
+	server.tool(
+		"lpm_package_info",
+		"Get metadata for an LPM package including versions, description, downloads, AI analysis, compatibility, and readme",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+		},
+		params => packageInfo(params, context),
+	)
+
+	server.tool(
+		"lpm_quality_report",
+		"Get the quality score and detailed check breakdown for an LPM package (27 checks across documentation, code, testing, health)",
+		{
+			name: z.string().describe("Package name in owner.package-name format"),
+		},
+		params => qualityReport(params, context),
+	)
+
+	server.tool(
+		"lpm_api_docs",
+		"Get structured API documentation for an LPM package — functions, classes, interfaces, type aliases, enums, and variables with signatures, params, return types, and descriptions. Use this to understand how to use a package before installing it.",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to get docs for (defaults to latest)"),
+		},
+		params => apiDocs(params, context),
+	)
+
+	server.tool(
+		"lpm_llm_context",
+		"Get an LLM-optimized usage guide for an LPM package — purpose, quickStart code, key exports with signatures, common usage patterns, gotchas, and when to use it. Use this to quickly understand how to use a package correctly.",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to get context for (defaults to latest)"),
+		},
+		params => llmContext(params, context),
+	)
+
+	server.tool(
+		"lpm_package_context",
+		"Get complete context for an LPM package in a single call — combines condensed package metadata (name, version, description, install method, dependencies), structured API docs (functions, classes, types), and LLM usage guide (quickStart, patterns, gotchas). Use this as the primary tool when you need to understand and use a package.",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to get context for (defaults to latest)"),
+		},
+		params => packageContext(params, context),
+	)
+
+	server.tool(
+		"lpm_package_skills",
+		"Get author-written Agent Skills for an LPM package - usage patterns, anti-patterns, gotchas, and best practices. Skills are version-specific and automatically resolve from local package.json if no version is specified.",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe(
+					"Specific version to get skills for (defaults to version in local package.json, then latest)",
+				),
+		},
+		params => packageSkills(params, context),
+	)
+
+	server.tool(
+		"lpm_pool_stats",
+		"Get your Pool revenue sharing earnings estimate for the current month. Shows per-package breakdown with installs, share %, and estimated earnings. Requires authentication.",
+		{},
+		params => poolStats(params, context),
+	)
+
+	server.tool(
+		"lpm_search_owners",
+		"Search for users or organizations on the LPM registry by name or username.",
+		{
+			query: z.string().describe("Name or username to search for"),
+			limit: z
+				.number()
+				.min(1)
+				.max(10)
+				.optional()
+				.describe("Maximum number of results (1-10, default 5)"),
+		},
+		params => searchOwners(params, context),
+	)
+
+	server.tool(
+		"lpm_packages_by_owner",
+		"List packages published by a specific user or organization on the LPM registry. Shows public packages with distribution mode.",
+		{
+			owner: z
+				.string()
+				.describe("Username or organization slug to list packages for"),
+			limit: z
+				.number()
+				.min(1)
+				.max(50)
+				.optional()
+				.describe("Maximum number of results (1-50, default 10)"),
+		},
+		params => packagesByOwner(params, context),
+	)
+
+	server.tool(
+		"lpm_user_info",
+		"Get information about the authenticated LPM user including organizations, plan tier, pool access, and usage limits. Requires authentication.",
+		{},
+		params => userInfo(params, context),
+	)
+
+	server.tool(
+		"lpm_get_install_command",
+		"Get the correct CLI command to install an LPM package. Returns either `lpm add` (extracts source files for customization — components, blocks, Swift packages) or `lpm install` (installs to node_modules as a dependency — libraries, utilities).",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to install (defaults to latest)"),
+		},
+		params => getInstallCommand(params, context),
+	)
+
+	server.tool(
+		"lpm_add",
+		"Add an LPM package to the project by extracting source files for customization. Use for UI components, blocks, templates, Swift packages, and MCP servers. Requires LPM CLI installed.",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to install (defaults to latest)"),
+			path: z
+				.string()
+				.optional()
+				.describe(
+					"Target directory for installation (e.g., src/components/ui)",
+				),
+			alias: z
+				.string()
+				.optional()
+				.describe("Import alias prefix for rewriting (e.g., @/components/ui)"),
+			target: z
+				.string()
+				.optional()
+				.describe("Swift SPM target name (for Swift packages)"),
+			force: z
+				.boolean()
+				.optional()
+				.describe("Overwrite existing files without prompting"),
+			installDeps: z
+				.boolean()
+				.optional()
+				.describe(
+					"Auto-install npm dependencies (default: true, set false to skip)",
+				),
+			config: z
+				.record(z.string())
+				.optional()
+				.describe(
+					'Config schema params as key-value pairs (e.g., { "styling": "panda" })',
+				),
+		},
+		params => add(params, context),
+	)
+
+	server.tool(
+		"lpm_install",
+		"Install an LPM package as a dependency to node_modules (like npm install). Use for JS libraries, utilities, and SDKs. Requires LPM CLI installed.",
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to install (defaults to latest)"),
+		},
+		params => install(params, context),
+	)
+
+	server.tool(
+		"lpm_browse_source",
+		`Browse source code of an LPM package you have access to. Use without \`path\` to see the file tree first, then request specific files or directories with \`path\`. Requires authentication. Pool packages require Pool subscription, marketplace packages require a license.
+
+IMPORTANT: Prefer fetching directory paths (e.g., "src", "components") to get all files under that directory in a single request, rather than requesting individual files one by one. To get ALL source files at once, pass an empty string "" as path.`,
+		{
+			name: z
+				.string()
+				.describe(
+					"Package name in owner.package-name or @lpm.dev/owner.package-name format",
+				),
+			version: z
+				.string()
+				.optional()
+				.describe("Specific version to browse (defaults to latest)"),
+			path: z
+				.string()
+				.optional()
+				.describe(
+					'File or directory path to browse (e.g., "src/index.js" or "src"). Omit to get file tree only. Pass empty string "" to get ALL source files at once.',
+				),
+		},
+		params => browseSource(params, context),
+	)
+
+	server.tool(
+		"lpm_search",
+		"Search LPM packages using natural language or structured filters. Uses hybrid semantic search for natural language queries. Supports filtering by category, distribution mode, package type, ecosystem, license, and more.",
+		{
+			query: z
+				.string()
+				.optional()
+				.describe(
+					'Natural language search query (e.g., "validate user input", "react component library")',
+				),
+			category: z
+				.string()
+				.optional()
+				.describe("Package category to filter by (e.g., ui-components, tools)"),
+			ecosystem: z
+				.enum(["js", "swift", "xcframework"])
+				.optional()
+				.describe(
+					'Filter by package ecosystem (e.g., "swift" for iOS/macOS packages)',
+				),
+			distribution: z
+				.enum(["marketplace", "pool", "private"])
+				.optional()
+				.describe("Filter by distribution mode"),
+			packageType: z
+				.enum([
+					"package",
+					"source",
+					"mcp-server",
+					"vscode-extension",
+					"cursor-rules",
+					"github-action",
+					"xcframework",
+					"other",
+				])
+				.optional()
+				.describe("Filter by package type"),
+			sort: z
+				.enum(["newest", "popular", "name"])
+				.optional()
+				.describe(
+					"Sort order (default: relevance for search, newest for filtered)",
+				),
+			hasTypes: z
+				.boolean()
+				.optional()
+				.describe("Filter to packages with TypeScript type definitions"),
+			moduleType: z
+				.enum(["esm", "cjs", "dual"])
+				.optional()
+				.describe("Filter by JavaScript module type"),
+			license: z
+				.enum([
+					"MIT",
+					"Apache-2.0",
+					"ISC",
+					"GPL-3.0",
+					"BSD-3-Clause",
+					"Unlicense",
+				])
+				.optional()
+				.describe("Filter by license"),
+			minNodeVersion: z
+				.enum(["18", "20", "22"])
+				.optional()
+				.describe(
+					"Filter to packages supporting this Node.js version or lower",
+				),
+			limit: z
+				.number()
+				.min(1)
+				.max(50)
+				.optional()
+				.describe("Maximum number of results (1-50, default 10)"),
+		},
+		params => search(params, context),
+	)
+
+	return server
+}

package/lib/tools/add.js

@@ -0,0 +1,79 @@
+import { runCli } from "../cli.js"
+import { errorResponse, parseName, textResponse } from "../format.js"
+
+/**
+ * Add an LPM package to the user's project via the CLI.
+ * Extracts source files into the project for customization.
+ *
+ * @param {{ name: string, version?: string, path?: string, alias?: string, target?: string, force?: boolean, installDeps?: boolean, config?: Record<string, string> }} params
+ * @param {{ getToken: () => Promise<string|null> }} ctx
+ */
+export async function add(
+	{ name, version, path, alias, target, force, installDeps, config },
+	ctx,
+) {
+	let owner, pkgName
+	try {
+		const parsed = parseName(name)
+		owner = parsed.owner
+		pkgName = parsed.name
+	} catch (err) {
+		return errorResponse(err.message)
+	}
+
+	const token = await ctx.getToken()
+	if (!token) {
+		return errorResponse(
+			"Authentication required. Set LPM_TOKEN environment variable or run `lpm login`.",
+		)
+	}
+
+	// Build package reference with optional config params as URL query string
+	let pkgRef = `@lpm.dev/${owner}.${pkgName}`
+	if (version) pkgRef += `@${version}`
+
+	// Append config params as inline config (e.g., ?styling=panda&component=dialog)
+	if (config && typeof config === "object" && Object.keys(config).length > 0) {
+		const params = new URLSearchParams(config)
+		pkgRef += `?${params.toString()}`
+	}
+
+	// Build CLI args
+	const args = ["add", pkgRef, "--yes", "--json"]
+
+	if (path) args.push("--path", path)
+	if (alias) args.push("--alias", alias)
+	if (target) args.push("--target", target)
+	if (force) args.push("--force")
+	if (installDeps === false) args.push("--no-install-deps")
+
+	const result = await runCli(args)
+
+	if (!result.success) {
+		return errorResponse(result.error || "Failed to add package.")
+	}
+
+	// Format the result for the AI
+	const data = result.data
+	const summary = {
+		success: true,
+		package: data.package,
+		installPath: data.installPath,
+		alias: data.alias || null,
+		files: (data.files || []).map(f => ({
+			dest: f.dest,
+			action: f.action,
+		})),
+		dependencies: data.dependencies || { npm: [], lpm: [] },
+	}
+
+	if (data.config && Object.keys(data.config).length > 0) {
+		summary.config = data.config
+	}
+
+	if (data.warnings?.length > 0) {
+		summary.warnings = data.warnings
+	}
+
+	return textResponse(JSON.stringify(summary, null, 2))
+}

package/lib/tools/api-docs.js

@@ -0,0 +1,78 @@
+import { registryGet } from "../api.js"
+import { CACHE_TTL } from "../constants.js"
+import { errorResponse, parseName, textResponse } from "../format.js"
+import { resolveInstalledVersion } from "../resolve-version.js"
+
+/**
+ * Fetch the structured API documentation for an LPM package.
+ * Returns functions, interfaces, classes, type aliases, enums, and variables
+ * with signatures, params, return types, and descriptions.
+ *
+ * @param {{ name: string, version?: string }} params
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function apiDocs({ name, version }, ctx) {
+	let owner, pkgName
+	try {
+		const parsed = parseName(name)
+		owner = parsed.owner
+		pkgName = parsed.name
+	} catch (err) {
+		return errorResponse(err.message)
+	}
+
+	const token = await ctx.getToken()
+	const queryName = `${owner}.${pkgName}`
+
+	// Resolve version from local package.json if not specified
+	const resolvedVersion =
+		version || resolveInstalledVersion(queryName) || undefined
+	const versionKey = resolvedVersion || "latest"
+	const cacheKey = `api-docs:${queryName}:${versionKey}:auth=${!!token}`
+
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	const baseUrl = ctx.getBaseUrl()
+	const params = new URLSearchParams({ name: queryName })
+	if (resolvedVersion) params.set("version", resolvedVersion)
+
+	const result = await registryGet(
+		`/api-docs?${params.toString()}`,
+		token,
+		baseUrl,
+	)
+
+	if (!result.ok) {
+		if (result.status === 404) {
+			const label = resolvedVersion
+				? `${queryName}@${resolvedVersion}`
+				: queryName
+			return errorResponse(`Package ${label} not found.`)
+		}
+		if (result.status === 403) {
+			return errorResponse(
+				"Access denied. Private packages require authentication from the package owner.",
+			)
+		}
+		return errorResponse(
+			result.data?.error || `Request failed (${result.status})`,
+		)
+	}
+
+	const data = result.data
+
+	// If docs aren't available yet, return a helpful message
+	if (!data.available) {
+		const response = textResponse(
+			`API docs for ${data.name}@${data.version}: ${data.message}`,
+		)
+		// Cache unavailable status for a shorter time (1 min) so retries work
+		ctx.cache.set(cacheKey, response, 60_000)
+		return response
+	}
+
+	const response = textResponse(JSON.stringify(data, null, 2))
+	ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+	return response
+}

package/lib/tools/browse-source.js

@@ -0,0 +1,111 @@
+import { registryGet } from "../api.js"
+import { CACHE_TTL } from "../constants.js"
+import { errorResponse, parseName, textResponse } from "../format.js"
+
+/**
+ * Browse source code of an LPM package.
+ *
+ * Calls the registry source browsing API endpoint:
+ *   GET /api/registry/@lpm.dev/{owner}.{name}/source?version=...&path=...
+ *
+ * - Without `path`: returns file tree only (use this first to explore structure)
+ * - With `path`: returns file tree + source contents for matching files/directory
+ *
+ * @param {{ name: string, version?: string, path?: string }} params
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function browseSource({ name, version, path }, ctx) {
+	let owner, pkgName
+	try {
+		const parsed = parseName(name)
+		owner = parsed.owner
+		pkgName = parsed.name
+	} catch (err) {
+		return errorResponse(err.message)
+	}
+
+	const token = await ctx.getToken()
+	if (!token) {
+		return errorResponse(
+			"Authentication required to browse source code. Set LPM_TOKEN environment variable.",
+		)
+	}
+
+	// Build cache key (includes path for content requests)
+	const cacheKey = `browse-source:${owner}.${pkgName}:${version || "latest"}:${path || ""}`
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	// Build query string
+	// path can be "" (all files), a specific path, or undefined (tree only)
+	const params = new URLSearchParams()
+	if (version) params.set("version", version)
+	if (path != null) params.set("path", path)
+	const qs = params.toString()
+
+	const baseUrl = ctx.getBaseUrl()
+	const url = `/@lpm.dev/${owner}.${pkgName}/source${qs ? `?${qs}` : ""}`
+	const result = await registryGet(url, token, baseUrl)
+
+	if (!result.ok) {
+		if (result.status === 404) {
+			const versionLabel = version || "latest"
+			return errorResponse(
+				`Version ${versionLabel} not found for @lpm.dev/${owner}.${pkgName}.`,
+			)
+		}
+		if (result.status === 401) {
+			return errorResponse(
+				"Authentication failed. Your token may be expired. Run `lpm login` to re-authenticate.",
+			)
+		}
+		if (result.status === 403) {
+			return errorResponse(
+				result.data?.error ||
+					"Access denied. You may need a Pool subscription or license to browse this package.",
+			)
+		}
+		if (result.status === 429) {
+			return errorResponse("Rate limit exceeded. Wait a minute and try again.")
+		}
+		if (result.status === 503) {
+			return errorResponse("Source browsing is currently disabled.")
+		}
+		return errorResponse(
+			result.data?.error || `Request failed (${result.status})`,
+		)
+	}
+
+	const data = result.data
+
+	// Format response
+	const response = {
+		package: data.package,
+		version: data.version,
+		ecosystem: data.ecosystem,
+	}
+
+	// Always include tree
+	response.tree = data.tree || []
+
+	// Include files if present (only when path was requested)
+	if (data.files && data.files.length > 0) {
+		response.files = data.files
+	}
+
+	// Include truncation warning
+	if (data.truncated) {
+		response.truncated = true
+		response.warning =
+			"Response was truncated due to size limits. Use the `path` parameter to request specific files or directories."
+	}
+
+	// Include package config if present (helps AI understand package structure)
+	if (data.lpmConfig) {
+		response.lpmConfig = data.lpmConfig
+	}
+
+	const mcpResponse = textResponse(JSON.stringify(response, null, 2))
+	ctx.cache.set(cacheKey, mcpResponse, CACHE_TTL.SHORT)
+	return mcpResponse
+}

package/lib/tools/get-install-command.js

@@ -0,0 +1,73 @@
+import { registryGet } from "../api.js"
+import { CACHE_TTL } from "../constants.js"
+import { errorResponse, parseName, textResponse } from "../format.js"
+
+/**
+ * Get the correct CLI install command for an LPM package.
+ * Returns `lpm add` for source packages (components, blocks, MCP servers, Swift)
+ * or `lpm install` for dependency packages (installed to node_modules).
+ *
+ * @param {{ name: string, version?: string }} params
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function getInstallCommand({ name, version }, ctx) {
+	let owner, pkgName
+	try {
+		const parsed = parseName(name)
+		owner = parsed.owner
+		pkgName = parsed.name
+	} catch (err) {
+		return errorResponse(err.message)
+	}
+
+	const fullName = `@lpm.dev/${owner}.${pkgName}`
+	const versionSuffix = version ? `@${version}` : ""
+
+	const token = await ctx.getToken()
+	const cacheKey = `install-cmd:${owner}.${pkgName}:auth=${!!token}`
+
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	const baseUrl = ctx.getBaseUrl()
+	const result = await registryGet(`/${fullName}`, token, baseUrl)
+
+	if (!result.ok) {
+		// Fallback: return `lpm add` as the default command when metadata is unavailable
+		if (result.status === 404) {
+			return errorResponse(`Package ${fullName} not found.`)
+		}
+		const response = textResponse(`lpm add ${fullName}${versionSuffix}`)
+		return response
+	}
+
+	const data = result.data
+	const ecosystem = data.ecosystem || "js"
+	const packageType = data.packageType || "package"
+
+	// Source-based packages use `lpm add` (extracts files into the project)
+	// Only plain JS packages without a special type use `lpm install` (node_modules)
+	const useAdd =
+		ecosystem !== "js" ||
+		packageType !== "package" ||
+		data.lpmSource ||
+		data.hasLpmConfig
+
+	const command = useAdd
+		? `lpm add ${fullName}${versionSuffix}`
+		: `lpm install ${fullName}${versionSuffix}`
+
+	const explanation = useAdd
+		? "Extracts source files into your project for customization."
+		: "Installs as a dependency in node_modules (like npm install)."
+
+	const response = textResponse(
+		JSON.stringify(
+			{ command, method: useAdd ? "add" : "install", explanation },
+			null,
+			2,
+		),
+	)
+	ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+	return response
+}