get_best_practices

Instructions

Implementation Reference

• lib/mcp-tools.ts:186-227 (handler)

  The core handler for the get_best_practices tool. Accepts ecosystem (required) and category (optional, defaults to 'best_practices'). Queries the content_items table filtered by ecosystem slug and category, excludes quarantined items, filters out pro-only content for free tier users, and returns items with freshness metadata via freshnessEnvelope().

  if (name === 'get_best_practices') {
    const ecosystem = args.ecosystem as string
    const category = (args.category as string | undefined) ?? 'best_practices'
  
    const access = await checkEcosystemAccess(supabase, ecosystem, profile.tier)
    if (!access.ok) {
      await logApiRequest(supabase, { apiKey: profile.api_key, tool: 'best-practices', ecosystem, statusCode: access.response.status })
      return err('Error: Ecosystem not available on free tier. Upgrade at usestrata.dev/dashboard/billing', access.response.status)
    }
  
    let query = supabase
      .from('content_items')
      .select('id, title, body, source_url, published_at, last_verified_at, confidence, source_count, created_at')
      .eq('ecosystem_slug', access.slug)
      .eq('category', category)
      .eq('is_quarantined', false)
      .order('published_at', { ascending: false })
  
    if (profile.tier === 'free') query = query.eq('is_pro_only', false)
  
    const { data, error } = await query
    if (error) {
      await logApiRequest(supabase, { apiKey: profile.api_key, tool: 'best-practices', ecosystem, statusCode: 500 })
      return err('Error: Database error', 500)
    }
  
    type Row = { id: string; title: string; body: string; source_url: string | null; published_at: string; last_verified_at: string | null; confidence: string | null; source_count: number | null; created_at: string }
    const rows = (data ?? []) as Row[]
    const items = rows.map((row) => ({
      id: row.id,
      title: row.title,
      body: row.body,
      source_urls: row.source_url ? [row.source_url] : [],
      confidence: row.confidence ?? 'medium',
      source_count: row.source_count ?? 1,
      updated_at: row.created_at,
      ...freshnessEnvelope(row.published_at ?? row.created_at, row.last_verified_at),
    }))
  
    await logApiRequest(supabase, { apiKey: profile.api_key, tool: 'best-practices', ecosystem, statusCode: 200 })
    return ok({ ecosystem, category, items }, rows.map(r => r.id))
  }

• lib/mcp-tools.ts:27-47 (schema)

  Tool definition and input schema for get_best_practices. Defines ecosystem (required string) and category (optional string, default 'best_practices') as inputs.

  {
    name: 'get_best_practices',
    description:
      'Get AI-verified best practices for a given AI ecosystem and category. Returns current, production-ready guidance for developers. ' +
      'Each item includes content_age_hours and data_freshness — check these before acting on time-sensitive information. ' +
      EPISTEMIC_NOTICE,
    inputSchema: {
      type: 'object',
      properties: {
        ecosystem: {
          type: 'string',
          description: 'AI ecosystem slug. Call list_ecosystems first to see all available slugs for your tier.',
        },
        category: {
          type: 'string',
          description: 'Content category. Defaults to best_practices',
        },
      },
      required: ['ecosystem'],
    },
  },

• scripts/mcp-stdio.ts:34-41 (registration)

  Registration of get_best_practices in the stdio MCP server (scripts/mcp-stdio.ts). Uses TOOL_DEFINITIONS[0] for the description and Zod schemas for input validation.

  server.registerTool(
    'get_best_practices',
    {
      description: TOOL_DEFINITIONS[0].description,
      inputSchema: { ecosystem: z.string(), category: z.string().optional() },
    },
    (args) => handleToolCall('get_best_practices', args as Record<string, unknown>, mockReq),
  )

• app/mcp/route.ts:26-33 (registration)

  Registration of get_best_practices in the HTTP/streaming MCP server (app/mcp/route.ts POST handler). Routes to the same handler via handleToolCall.

  server.registerTool(
    'get_best_practices',
    {
      description: TOOL_DEFINITIONS[0].description,
      inputSchema: { ecosystem: z.string(), category: z.string().optional() },
    },
    (args) => handleToolCall('get_best_practices', args as Record<string, unknown>, req),
  )

• lib/freshness.ts:9-25 (helper)

  Helper function freshnessEnvelope() used by the handler to compute content_age_hours, last_verified_at, and data_freshness (live/recent/stale/very_stale) for each returned item.

  export function freshnessEnvelope(
    publishedAt: string,
    lastVerifiedAt: string | null,
  ): FreshnessEnvelope {
    const ageMs = Date.now() - new Date(publishedAt).getTime()
    const ageHours = Math.round(ageMs / 3.6e6)
    const bucket: FreshnessBucket =
      ageHours < 12 ? 'live'
      : ageHours < 48 ? 'recent'
      : ageHours < 168 ? 'stale'
      : 'very_stale'
    return {
      content_age_hours: ageHours,
      last_verified_at: lastVerifiedAt ?? publishedAt,
      data_freshness: bucket,
    }
  }