pub-mcp 0.1.0

package/src/clients/pubClient.ts

@@ -0,0 +1,312 @@
+import type {
+  PackageInfo,
+  PackageVersion,
+  SearchResult,
+  PackageScore,
+  PackageChangelog,
+} from '../types/index.js';
+import { getPackageCache, getSearchCache } from '../cache/cache.js';
+
+const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_RETRIES = 3;
+
+export interface PubClientOptions {
+  baseUrl?: string;
+  timeout?: number;
+  retries?: number;
+}
+
+export class PubClientError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+    public isRetryable: boolean = false
+  ) {
+    super(message);
+    this.name = 'PubClientError';
+  }
+}
+
+export class PubClient {
+  private baseUrl: string;
+  private timeout: number;
+  private retries: number;
+
+  constructor(options: PubClientOptions = {}) {
+    this.baseUrl = options.baseUrl || process.env.PUB_DEV_API_URL || 'https://pub.dev/api';
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    this.retries = options.retries || DEFAULT_RETRIES;
+  }
+
+  private async fetchWithTimeout(url: string, options: RequestInit = {}): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+      return response;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  private async fetchWithRetry(url: string, options: RequestInit = {}): Promise<Response> {
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt < this.retries; attempt++) {
+      try {
+        const response = await this.fetchWithTimeout(url, options);
+
+        if (!response.ok) {
+          const isRetryable =
+            response.status === 429 || (response.status >= 500 && response.status < 600);
+          if (isRetryable && attempt < this.retries - 1) {
+            await this.delay(Math.pow(2, attempt) * 1000);
+            continue;
+          }
+
+          throw new PubClientError(
+            `HTTP error: ${response.status} ${response.statusText}`,
+            response.status,
+            isRetryable
+          );
+        }
+
+        return response;
+      } catch (error) {
+        lastError = error as Error;
+        if (attempt < this.retries - 1 && lastError.name === 'AbortError') {
+          await this.delay(Math.pow(2, attempt) * 1000);
+        }
+      }
+    }
+
+    throw lastError || new PubClientError('Failed to fetch after retries');
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async searchPackages(query: string, limit: number = 10): Promise<SearchResult> {
+    const cacheKey = `search:${query}:${limit}`;
+    const cached = getSearchCache().get(cacheKey);
+    if (cached) {
+      return cached as SearchResult;
+    }
+
+    const url = `${this.baseUrl}/search?q=${encodeURIComponent(query)}&limit=${limit}`;
+    const response = await this.fetchWithRetry(url);
+
+    const data = (await response.json()) as {
+      packages?: { package: string; version: string; description?: string }[];
+      totalCount?: number;
+    };
+
+    const packages = (data.packages || []).map((p) => ({
+      name: p.package,
+      description: p.description || '',
+      latestVersion: p.version,
+    }));
+
+    const result = {
+      packages,
+      total: data.totalCount || packages.length,
+    };
+
+    getSearchCache().set(cacheKey, result);
+    return result;
+  }
+
+  async getPackage(name: string): Promise<PackageInfo> {
+    const cacheKey = `package:${name}`;
+    const cached = getPackageCache().get(cacheKey);
+    if (cached) {
+      return cached as PackageInfo;
+    }
+
+    const url = `${this.baseUrl}/packages/${name}`;
+    const response = await this.fetchWithRetry(url);
+
+    if (response.status === 404) {
+      throw new PubClientError(`Package not found: ${name}`, 404, false);
+    }
+
+    const data = (await response.json()) as {
+      name: string;
+      latest: { version: string; published: string; description?: string };
+      publisher?: { publisherName?: string };
+      urls?: { homepage?: string; repository?: string; issues?: string };
+    };
+
+    const result: PackageInfo = {
+      name: data.name,
+      description: data.latest.description || '',
+      latestVersion: data.latest.version,
+      published: data.latest.published,
+      updated: data.latest.published,
+      publisher: data.publisher?.publisherName,
+      homepage: data.urls?.homepage,
+      repository: data.urls?.repository,
+      issues: data.urls?.issues,
+    };
+
+    getPackageCache().set(cacheKey, result);
+    return result;
+  }
+
+  async getPackageVersions(name: string): Promise<PackageVersion[]> {
+    const cacheKey = `versions:${name}`;
+    const cached = getPackageCache().get(cacheKey);
+    if (cached) {
+      return cached as PackageVersion[];
+    }
+
+    const url = `${this.baseUrl}/packages/${name}`;
+    const response = await this.fetchWithRetry(url);
+
+    if (response.status === 404) {
+      throw new PubClientError(`Package not found: ${name}`, 404, false);
+    }
+
+    const data = (await response.json()) as {
+      versions: { version: string; published: string }[];
+    };
+
+    const result = data.versions.map((v) => ({
+      version: v.version,
+      published: v.published,
+    }));
+
+    getPackageCache().set(cacheKey, result);
+    return result;
+  }
+
+  async getReadme(name: string, version?: string): Promise<string> {
+    const cacheKey = `readme:${name}:${version || 'latest'}`;
+    const cached = getPackageCache().get(cacheKey);
+    if (cached) {
+      return cached as string;
+    }
+
+    const versionPart = version ? `/${version}` : '';
+    const url = `${this.baseUrl}/packages/${name}${versionPart}/readme`;
+
+    try {
+      const response = await this.fetchWithRetry(url);
+
+      if (response.status === 404) {
+        return '';
+      }
+
+      const content = await response.text();
+      getPackageCache().set(cacheKey, content);
+      return content;
+    } catch (error) {
+      if (error instanceof PubClientError && error.statusCode === 404) {
+        return '';
+      }
+      throw error;
+    }
+  }
+
+  async getDependencies(name: string, version?: string): Promise<Record<string, string>> {
+    const cacheKey = `deps:${name}:${version || 'latest'}`;
+    const cached = getPackageCache().get(cacheKey);
+    if (cached) {
+      return cached as Record<string, string>;
+    }
+
+    const versionPart = version ? `/${version}` : '';
+    const url = `${this.baseUrl}/packages/${name}${versionPart}`;
+    const response = await this.fetchWithRetry(url);
+
+    if (response.status === 404) {
+      throw new PubClientError(`Package not found: ${name}`, 404, false);
+    }
+
+    const data = (await response.json()) as {
+      latest?: { dependencies?: Record<string, string> };
+    };
+
+    const result = data.latest?.dependencies || {};
+    getPackageCache().set(cacheKey, result);
+    return result;
+  }
+
+  async getPackageScore(name: string): Promise<PackageScore> {
+    const cacheKey = `score:${name}`;
+    const cached = getPackageCache().get(cacheKey);
+    if (cached) {
+      return cached as PackageScore;
+    }
+
+    const url = `${this.baseUrl}/packages/${name}/score`;
+    const response = await this.fetchWithRetry(url);
+
+    if (response.status === 404) {
+      throw new PubClientError(`Package not found: ${name}`, 404, false);
+    }
+
+    const data = (await response.json()) as {
+      grantedPoints?: number;
+      maxPoints?: number;
+      likeCount?: number;
+      downloadCount30Days?: number;
+      tags?: string[];
+    };
+
+    const result: PackageScore = {
+      grantedPoints: data.grantedPoints ?? 0,
+      maxPoints: data.maxPoints ?? 0,
+      likeCount: data.likeCount ?? 0,
+      downloadCount30Days: data.downloadCount30Days ?? 0,
+      tags: data.tags ?? [],
+    };
+
+    getPackageCache().set(cacheKey, result);
+    return result;
+  }
+
+  async getChangelog(name: string, version?: string): Promise<PackageChangelog | null> {
+    const cacheKey = `changelog:${name}:${version || 'latest'}`;
+    const cached = getPackageCache().get(cacheKey);
+    if (cached) {
+      return cached as PackageChangelog;
+    }
+
+    const versionPart = version ? `/${version}` : '';
+    const url = `${this.baseUrl}/packages/${name}${versionPart}/changelog`;
+
+    try {
+      const response = await this.fetchWithRetry(url);
+
+      if (response.status === 404) {
+        return null;
+      }
+
+      const data = (await response.json()) as {
+        version: string;
+        published: string;
+        content?: string;
+      };
+
+      const result: PackageChangelog = {
+        version: data.version,
+        published: data.published,
+        content: data.content || '',
+      };
+
+      getPackageCache().set(cacheKey, result);
+      return result;
+    } catch (error) {
+      if (error instanceof PubClientError && error.statusCode === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,266 @@
+import { z } from 'zod';
+import type { PubClient } from '../clients/pubClient.js';
+import type { GitHubClient } from '../clients/githubClient.js';
+import { parseGitHubUrl } from '../clients/githubClient.js';
+
+export const searchPackagesSchema = z.object({
+  query: z.string().min(1),
+  limit: z.number().int().min(1).max(100).default(10),
+});
+
+export const getPackageInfoSchema = z.object({
+  name: z.string().min(1),
+});
+
+export const getPackageVersionsSchema = z.object({
+  name: z.string().min(1),
+});
+
+export const getReadmeSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().optional(),
+  format: z.enum(['markdown', 'text', 'html']).default('markdown').optional(),
+});
+
+export const getDependenciesSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().optional(),
+});
+
+export const getPackageScoreSchema = z.object({
+  name: z.string().min(1),
+});
+
+export const getChangelogSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().optional(),
+});
+
+export const getPackageMetricsSchema = z.object({
+  name: z.string().min(1),
+});
+
+export type SearchPackagesInput = { query: string; limit?: number };
+export type GetPackageInfoInput = { name: string };
+export type GetPackageVersionsInput = { name: string };
+export type GetReadmeInput = {
+  name: string;
+  version?: string;
+  format?: 'markdown' | 'text' | 'html';
+};
+export type GetDependenciesInput = { name: string; version?: string };
+export type GetPackageScoreInput = { name: string };
+export type GetChangelogInput = { name: string; version?: string };
+export type GetPackageMetricsInput = { name: string };
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+export const tools: ToolDefinition[] = [
+  {
+    name: 'search_packages',
+    description: 'Search for packages on pub.dev by query',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query string' },
+        limit: { type: 'number', description: 'Maximum number of results (default 10)' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'get_package_info',
+    description: 'Get detailed information about a specific package',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_package_versions',
+    description: 'Get all available versions of a package',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_readme',
+    description: 'Get the README content of a package',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+        version: { type: 'string', description: 'Specific version (optional, defaults to latest)' },
+        format: {
+          type: 'string',
+          description: 'Output format: markdown, text, or html (default: markdown)',
+          enum: ['markdown', 'text', 'html'],
+        },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_dependencies',
+    description: 'Get the dependencies of a package',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+        version: { type: 'string', description: 'Specific version (optional, defaults to latest)' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_package_score',
+    description: 'Get package score and metrics (pana points, likes, downloads, tags)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_changelog',
+    description: 'Get the changelog of a specific package version',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+        version: { type: 'string', description: 'Specific version (optional, defaults to latest)' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_package_metrics',
+    description: 'Get comprehensive metrics for a package (info + score + versions)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Package name' },
+      },
+      required: ['name'],
+    },
+  },
+];
+
+export async function handleSearchPackages(client: PubClient, input: SearchPackagesInput) {
+  const result = await client.searchPackages(input.query, input.limit);
+  return {
+    packages: result.packages.map((p) => ({
+      name: p.name,
+      description: p.description,
+      latestVersion: p.latestVersion,
+    })),
+    total: result.total,
+  };
+}
+
+export async function handleGetPackageInfo(client: PubClient, input: GetPackageInfoInput) {
+  const pkg = await client.getPackage(input.name);
+  return pkg;
+}
+
+export async function handleGetPackageVersions(client: PubClient, input: GetPackageVersionsInput) {
+  const versions = await client.getPackageVersions(input.name);
+  return { versions };
+}
+
+export async function handleGetReadme(
+  client: PubClient,
+  githubClient: GitHubClient,
+  input: GetReadmeInput
+) {
+  const readme = await client.getReadme(input.name, input.version);
+
+  let finalReadme = readme;
+  let source = 'pub.dev';
+
+  if (!readme && input.name) {
+    try {
+      const pkg = await client.getPackage(input.name);
+      if (pkg.repository) {
+        const parsed = parseGitHubUrl(pkg.repository);
+        if (parsed) {
+          const githubReadme = await githubClient.getRepositoryReadme(parsed.owner, parsed.repo);
+          if (githubReadme) {
+            finalReadme = githubReadme;
+            source = 'github';
+          }
+        }
+      }
+    } catch {
+      // ignore errors and return no readme
+    }
+  }
+
+  const content = finalReadme || 'No README available';
+
+  if (input.format === 'text') {
+    return {
+      readme: content.replace(/[#*`_~\[\]]/g, '').trim(),
+      source,
+      format: 'text',
+    };
+  }
+
+  return { readme: content, source, format: input.format || 'markdown' };
+}
+
+export async function handleGetDependencies(client: PubClient, input: GetDependenciesInput) {
+  const dependencies = await client.getDependencies(input.name, input.version);
+  return { dependencies };
+}
+
+export async function handleGetPackageScore(client: PubClient, input: GetPackageScoreInput) {
+  const score = await client.getPackageScore(input.name);
+  return score;
+}
+
+export async function handleGetChangelog(client: PubClient, input: GetChangelogInput) {
+  const changelog = await client.getChangelog(input.name, input.version);
+
+  if (!changelog) {
+    return {
+      version: input.version || 'latest',
+      content: 'No changelog available',
+      published: '',
+    };
+  }
+
+  return changelog;
+}
+
+export async function handleGetPackageMetrics(client: PubClient, input: GetPackageMetricsInput) {
+  const [info, score, versions] = await Promise.all([
+    client.getPackage(input.name),
+    client.getPackageScore(input.name),
+    client.getPackageVersions(input.name),
+  ]);
+
+  return {
+    info,
+    score,
+    versionCount: versions.length,
+    latestVersion: versions[0]?.version,
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,61 @@
+export interface PackageInfo {
+  name: string;
+  description: string;
+  latestVersion: string;
+  published: string;
+  updated: string;
+  publisher?: string;
+  homepage?: string;
+  repository?: string;
+  issues?: string;
+}
+
+export interface PackageVersion {
+  version: string;
+  published: string;
+}
+
+export interface PackageScore {
+  grantedPoints: number;
+  maxPoints: number;
+  likeCount: number;
+  downloadCount30Days: number;
+  tags: string[];
+}
+
+export interface PackageChangelog {
+  version: string;
+  published: string;
+  content: string;
+}
+
+export interface PackageDependencies {
+  direct: Record<string, string>;
+  dev: Record<string, string>;
+  transitive: Record<string, string>;
+}
+
+export interface SearchResult {
+  packages: {
+    name: string;
+    description: string;
+    latestVersion: string;
+  }[];
+  total: number;
+}
+
+export interface ToolInput {
+  query?: string;
+  limit?: number;
+  name?: string;
+  version?: string;
+}
+
+export interface ToolOutput {
+  packages?: PackageInfo[];
+  versions?: PackageVersion[];
+  readme?: string;
+  dependencies?: PackageDependencies;
+  searchResults?: SearchResult;
+  [key: string]: unknown;
+}

package/src/utils/rateLimiter.ts

@@ -0,0 +1,56 @@
+import pLimit from 'p-limit';
+
+const MAX_CONCURRENT = parseInt(process.env.MAX_CONCURRENT_REQUESTS || '5', 10);
+const RETRY_ATTEMPTS = parseInt(process.env.RETRY_ATTEMPTS || '3', 10);
+
+export class RateLimiter {
+  private limit: ReturnType<typeof pLimit>;
+  
+  constructor(concurrency: number = MAX_CONCURRENT) {
+    this.limit = pLimit(concurrency);
+  }
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    return this.limit(fn);
+  }
+
+  setConcurrency(concurrency: number): void {
+    this.limit = pLimit(concurrency);
+  }
+}
+
+export const rateLimiter = new RateLimiter();
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { attempts?: number; backoff?: number } = {}
+): Promise<T> {
+  const attempts = options.attempts || RETRY_ATTEMPTS;
+  const backoff = options.backoff || 1000;
+
+  let lastError: Error | null = null;
+
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      const isRetryable = error instanceof Error && 
+        ('statusCode' in error 
+          ? (error as { statusCode?: number }).statusCode === 429 
+          : error.message.includes('ECONNRESET') || error.message.includes('ETIMEDOUT'));
+
+      if (!isRetryable || i === attempts - 1) {
+        throw lastError;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, backoff * Math.pow(2, i)));
+    }
+  }
+
+  throw lastError;
+}
+
+export async function withRateLimit<T>(fn: () => Promise<T>): Promise<T> {
+  return rateLimiter.run(fn);
+}