midnight-mcp 0.1.0 → 0.1.2

package/dist/tools/repository/handlers.js

@@ -0,0 +1,311 @@
+/**
+ * Repository handler functions
+ * Business logic for repository-related MCP tools
+ */
+import { githubClient } from "../../pipeline/index.js";
+import { releaseTracker } from "../../pipeline/releases.js";
+import { logger, DEFAULT_REPOSITORIES } from "../../utils/index.js";
+import { REPO_ALIASES, EXAMPLES } from "./constants.js";
+/**
+ * Resolve repository name alias to owner/repo
+ */
+export function resolveRepo(repoName) {
+    // Default to compact if not provided
+    const name = repoName || "compact";
+    const normalized = name.toLowerCase().replace(/^midnightntwrk\//, "");
+    const alias = REPO_ALIASES[normalized];
+    if (alias)
+        return alias;
+    // Try to find in configured repos
+    for (const config of DEFAULT_REPOSITORIES) {
+        if (config.repo.toLowerCase() === normalized) {
+            return { owner: config.owner, repo: config.repo };
+        }
+    }
+    // Assume it's a full org/repo name
+    if (name.includes("/")) {
+        const [owner, repo] = name.split("/");
+        return { owner, repo };
+    }
+    return null;
+}
+/**
+ * Retrieve a specific file from Midnight repositories
+ */
+export async function getFile(input) {
+    logger.debug("Getting file", { repo: input.repo, path: input.path });
+    const repoInfo = resolveRepo(input.repo);
+    if (!repoInfo) {
+        return {
+            error: `Unknown repository: ${input.repo}`,
+            suggestion: `Valid repositories: ${Object.keys(REPO_ALIASES).join(", ")}`,
+        };
+    }
+    const file = await githubClient.getFileContent(repoInfo.owner, repoInfo.repo, input.path, input.ref);
+    if (!file) {
+        return {
+            error: `File not found: ${input.path}`,
+            repository: `${repoInfo.owner}/${repoInfo.repo}`,
+            suggestion: "Check the file path and try again. Use midnight:list-examples to see available example files.",
+        };
+    }
+    return {
+        content: file.content,
+        path: file.path,
+        repository: `${repoInfo.owner}/${repoInfo.repo}`,
+        sha: file.sha,
+        size: file.size,
+        url: `https://github.com/${repoInfo.owner}/${repoInfo.repo}/blob/${input.ref || "main"}/${file.path}`,
+    };
+}
+/**
+ * List available example contracts and DApps
+ */
+export async function listExamples(input) {
+    logger.debug("Listing examples", { category: input.category });
+    let filteredExamples = EXAMPLES;
+    if (input.category && input.category !== "all") {
+        filteredExamples = EXAMPLES.filter((e) => e.category === input.category);
+    }
+    return {
+        examples: filteredExamples.map((e) => ({
+            name: e.name,
+            repository: e.repository,
+            description: e.description,
+            complexity: e.complexity,
+            mainFile: e.mainFile,
+            features: e.features,
+            githubUrl: `https://github.com/${e.repository}`,
+        })),
+        totalCount: filteredExamples.length,
+        categories: [...new Set(EXAMPLES.map((e) => e.category))],
+    };
+}
+/**
+ * Retrieve recent changes across Midnight repositories
+ */
+export async function getLatestUpdates(input) {
+    logger.debug("Getting latest updates", input);
+    // Default to last 7 days
+    const since = input.since || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const repos = input.repos?.map(resolveRepo).filter(Boolean) ||
+        DEFAULT_REPOSITORIES.map((r) => ({ owner: r.owner, repo: r.repo }));
+    const updates = [];
+    for (const repo of repos) {
+        if (!repo)
+            continue;
+        const commits = await githubClient.getRecentCommits(repo.owner, repo.repo, since, 10);
+        if (commits.length > 0) {
+            updates.push({
+                repository: `${repo.owner}/${repo.repo}`,
+                commits,
+            });
+        }
+    }
+    // Sort by most recent commit
+    updates.sort((a, b) => {
+        const aDate = a.commits[0]?.date || "";
+        const bDate = b.commits[0]?.date || "";
+        return bDate.localeCompare(aDate);
+    });
+    // Generate summary
+    const totalCommits = updates.reduce((sum, u) => sum + u.commits.length, 0);
+    const activeRepos = updates.filter((u) => u.commits.length > 0).length;
+    return {
+        summary: {
+            since,
+            totalCommits,
+            activeRepositories: activeRepos,
+            checkedRepositories: repos.length,
+        },
+        updates: updates.map((u) => ({
+            repository: u.repository,
+            commitCount: u.commits.length,
+            latestCommit: u.commits[0]
+                ? {
+                    message: u.commits[0].message.split("\n")[0], // First line only
+                    date: u.commits[0].date,
+                    author: u.commits[0].author,
+                    url: u.commits[0].url,
+                }
+                : null,
+            recentCommits: u.commits.slice(0, 5).map((c) => ({
+                message: c.message.split("\n")[0],
+                date: c.date,
+                sha: c.sha.substring(0, 7),
+            })),
+        })),
+    };
+}
+/**
+ * Get version and release info for a repository
+ */
+export async function getVersionInfo(input) {
+    logger.debug("Getting version info", input);
+    const resolved = resolveRepo(input.repo);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${input.repo}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    const versionInfo = await releaseTracker.getVersionInfo(resolved.owner, resolved.repo);
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        latestVersion: versionInfo.latestRelease?.tag || "No releases found",
+        latestStableVersion: versionInfo.latestStableRelease?.tag || "No stable releases",
+        publishedAt: versionInfo.latestRelease?.publishedAt || null,
+        releaseNotes: versionInfo.latestRelease?.body || null,
+        recentReleases: versionInfo.recentReleases.slice(0, 5).map((r) => ({
+            version: r.tag,
+            date: r.publishedAt.split("T")[0],
+            isPrerelease: r.isPrerelease,
+            url: r.url,
+        })),
+        recentBreakingChanges: versionInfo.changelog
+            .slice(0, 3)
+            .flatMap((c) => c.changes.breaking)
+            .slice(0, 10),
+        versionContext: releaseTracker.getVersionContext(versionInfo),
+    };
+}
+/**
+ * Check for breaking changes since a specific version
+ */
+export async function checkBreakingChanges(input) {
+    logger.debug("Checking breaking changes", input);
+    const resolved = resolveRepo(input.repo);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${input.repo}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    const outdatedInfo = await releaseTracker.isOutdated(resolved.owner, resolved.repo, input.currentVersion);
+    const breakingChanges = await releaseTracker.getBreakingChangesSince(resolved.owner, resolved.repo, input.currentVersion);
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        currentVersion: input.currentVersion,
+        latestVersion: outdatedInfo.latestVersion,
+        isOutdated: outdatedInfo.isOutdated,
+        versionsBehind: outdatedInfo.versionsBehind,
+        hasBreakingChanges: outdatedInfo.hasBreakingChanges,
+        breakingChanges: breakingChanges,
+        recommendation: outdatedInfo.hasBreakingChanges
+            ? `⚠️ Breaking changes detected! Review the ${breakingChanges.length} breaking change(s) before upgrading.`
+            : outdatedInfo.isOutdated
+                ? `✅ Safe to upgrade. No breaking changes detected since ${input.currentVersion}.`
+                : `✅ You're on the latest version.`,
+    };
+}
+/**
+ * Get migration guide between versions
+ */
+export async function getMigrationGuide(input) {
+    logger.debug("Getting migration guide", input);
+    const resolved = resolveRepo(input.repo);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${input.repo}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    const guide = await releaseTracker.getMigrationGuide(resolved.owner, resolved.repo, input.fromVersion, input.toVersion);
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        from: guide.from,
+        to: guide.to,
+        summary: {
+            breakingChangesCount: guide.breakingChanges.length,
+            deprecationsCount: guide.deprecations.length,
+            newFeaturesCount: guide.newFeatures.length,
+        },
+        breakingChanges: guide.breakingChanges,
+        deprecations: guide.deprecations,
+        newFeatures: guide.newFeatures,
+        migrationSteps: guide.migrationSteps,
+        migrationDifficulty: guide.breakingChanges.length === 0
+            ? "Easy - No breaking changes"
+            : guide.breakingChanges.length <= 3
+                ? "Moderate - Few breaking changes"
+                : "Complex - Multiple breaking changes, plan carefully",
+    };
+}
+/**
+ * Get a file at a specific version - critical for version-accurate recommendations
+ */
+export async function getFileAtVersion(input) {
+    logger.debug("Getting file at version", input);
+    const resolved = resolveRepo(input.repo);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${input.repo}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    const result = await releaseTracker.getFileAtVersion(resolved.owner, resolved.repo, input.path, input.version);
+    if (!result) {
+        throw new Error(`File not found: ${input.path} at version ${input.version} in ${input.repo}`);
+    }
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        path: input.path,
+        version: result.version,
+        content: result.content,
+        note: `This is the exact content at version ${result.version}. Use this as the source of truth for syntax and API at this version.`,
+    };
+}
+/**
+ * Compare syntax between two versions - shows what changed
+ */
+export async function compareSyntax(input) {
+    logger.debug("Comparing syntax between versions", input);
+    const resolved = resolveRepo(input.repo);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${input.repo}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    // If no newVersion specified, get latest
+    let newVersion = input.newVersion;
+    if (!newVersion) {
+        const versionInfo = await releaseTracker.getVersionInfo(resolved.owner, resolved.repo);
+        newVersion =
+            versionInfo.latestStableRelease?.tag ||
+                versionInfo.latestRelease?.tag ||
+                "main";
+    }
+    const comparison = await releaseTracker.compareSyntax(resolved.owner, resolved.repo, input.path, input.oldVersion, newVersion);
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        path: input.path,
+        oldVersion: comparison.oldVersion,
+        newVersion: comparison.newVersion,
+        hasDifferences: comparison.hasDifferences,
+        oldContent: comparison.oldContent,
+        newContent: comparison.newContent,
+        recommendation: comparison.hasDifferences
+            ? `⚠️ This file has changed between ${comparison.oldVersion} and ${comparison.newVersion}. Review the differences before using code patterns from the old version.`
+            : `✅ No changes in this file between versions.`,
+    };
+}
+/**
+ * Get the latest syntax reference for Compact language
+ * This is the source of truth for writing valid, compilable contracts
+ */
+export async function getLatestSyntax(input) {
+    logger.debug("Getting latest syntax reference", input);
+    const resolved = resolveRepo(input.repo);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${input.repo}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    const reference = await releaseTracker.getLatestSyntaxReference(resolved.owner, resolved.repo);
+    if (!reference || reference.syntaxFiles.length === 0) {
+        // Fallback: get example contracts as syntax reference
+        const versionInfo = await releaseTracker.getVersionInfo(resolved.owner, resolved.repo);
+        const version = versionInfo.latestStableRelease?.tag || "main";
+        return {
+            repository: `${resolved.owner}/${resolved.repo}`,
+            version,
+            warning: "No grammar documentation found. Use example contracts as reference.",
+            syntaxFiles: [],
+            examplePaths: ["examples/", "test/", "contracts/"],
+        };
+    }
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        version: reference.version,
+        syntaxFiles: reference.syntaxFiles.map((f) => ({
+            path: f.path,
+            content: f.content,
+        })),
+        note: `This is the authoritative syntax reference at version ${reference.version}. Use this to ensure contracts are compilable.`,
+    };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/tools/repository/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Repository module exports
+ * Barrel file for repository-related tools
+ */
+export { GetFileInputSchema, ListExamplesInputSchema, GetLatestUpdatesInputSchema, GetVersionInfoInputSchema, CheckBreakingChangesInputSchema, GetMigrationGuideInputSchema, GetFileAtVersionInputSchema, CompareSyntaxInputSchema, GetLatestSyntaxInputSchema, type GetFileInput, type ListExamplesInput, type GetLatestUpdatesInput, type GetVersionInfoInput, type CheckBreakingChangesInput, type GetMigrationGuideInput, type GetFileAtVersionInput, type CompareSyntaxInput, type GetLatestSyntaxInput, } from "./schemas.js";
+export { REPO_ALIASES, EXAMPLES, type ExampleDefinition } from "./constants.js";
+export { resolveRepo, getFile, listExamples, getLatestUpdates, getVersionInfo, checkBreakingChanges, getMigrationGuide, getFileAtVersion, compareSyntax, getLatestSyntax, } from "./handlers.js";
+export { repositoryTools } from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/repository/index.js

@@ -0,0 +1,13 @@
+/**
+ * Repository module exports
+ * Barrel file for repository-related tools
+ */
+// Schemas and types
+export { GetFileInputSchema, ListExamplesInputSchema, GetLatestUpdatesInputSchema, GetVersionInfoInputSchema, CheckBreakingChangesInputSchema, GetMigrationGuideInputSchema, GetFileAtVersionInputSchema, CompareSyntaxInputSchema, GetLatestSyntaxInputSchema, } from "./schemas.js";
+// Constants
+export { REPO_ALIASES, EXAMPLES } from "./constants.js";
+// Handlers
+export { resolveRepo, getFile, listExamples, getLatestUpdates, getVersionInfo, checkBreakingChanges, getMigrationGuide, getFileAtVersion, compareSyntax, getLatestSyntax, } from "./handlers.js";
+// Tools
+export { repositoryTools } from "./tools.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/repository/schemas.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Repository tool input schemas
+ * Zod schemas for validating tool inputs
+ */
+import { z } from "zod";
+export declare const GetFileInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+    path: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    repo: string;
+    ref?: string | undefined;
+}, {
+    path: string;
+    repo: string;
+    ref?: string | undefined;
+}>;
+export declare const ListExamplesInputSchema: z.ZodObject<{
+    category: z.ZodDefault<z.ZodOptional<z.ZodEnum<["counter", "bboard", "token", "voting", "all"]>>>;
+}, "strip", z.ZodTypeAny, {
+    category: "all" | "counter" | "bboard" | "token" | "voting";
+}, {
+    category?: "all" | "counter" | "bboard" | "token" | "voting" | undefined;
+}>;
+export declare const GetLatestUpdatesInputSchema: z.ZodObject<{
+    since: z.ZodOptional<z.ZodString>;
+    repos: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    repos?: string[] | undefined;
+    since?: string | undefined;
+}, {
+    repos?: string[] | undefined;
+    since?: string | undefined;
+}>;
+export declare const GetVersionInfoInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+}, {
+    repo: string;
+}>;
+export declare const CheckBreakingChangesInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+    currentVersion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    currentVersion: string;
+}, {
+    repo: string;
+    currentVersion: string;
+}>;
+export declare const GetMigrationGuideInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+    fromVersion: z.ZodString;
+    toVersion: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    fromVersion: string;
+    toVersion?: string | undefined;
+}, {
+    repo: string;
+    fromVersion: string;
+    toVersion?: string | undefined;
+}>;
+export declare const GetFileAtVersionInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+    path: z.ZodString;
+    version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    repo: string;
+    version: string;
+}, {
+    path: string;
+    repo: string;
+    version: string;
+}>;
+export declare const CompareSyntaxInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+    path: z.ZodString;
+    oldVersion: z.ZodString;
+    newVersion: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    repo: string;
+    oldVersion: string;
+    newVersion?: string | undefined;
+}, {
+    path: string;
+    repo: string;
+    oldVersion: string;
+    newVersion?: string | undefined;
+}>;
+export declare const GetLatestSyntaxInputSchema: z.ZodObject<{
+    repo: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+}, {
+    repo?: string | undefined;
+}>;
+export type GetFileInput = z.infer<typeof GetFileInputSchema>;
+export type ListExamplesInput = z.infer<typeof ListExamplesInputSchema>;
+export type GetLatestUpdatesInput = z.infer<typeof GetLatestUpdatesInputSchema>;
+export type GetVersionInfoInput = z.infer<typeof GetVersionInfoInputSchema>;
+export type CheckBreakingChangesInput = z.infer<typeof CheckBreakingChangesInputSchema>;
+export type GetMigrationGuideInput = z.infer<typeof GetMigrationGuideInputSchema>;
+export type GetFileAtVersionInput = z.infer<typeof GetFileAtVersionInputSchema>;
+export type CompareSyntaxInput = z.infer<typeof CompareSyntaxInputSchema>;
+export type GetLatestSyntaxInput = z.infer<typeof GetLatestSyntaxInputSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tools/repository/schemas.js

@@ -0,0 +1,73 @@
+/**
+ * Repository tool input schemas
+ * Zod schemas for validating tool inputs
+ */
+import { z } from "zod";
+// Schema definitions
+export const GetFileInputSchema = z.object({
+    repo: z
+        .string()
+        .describe("Repository name (e.g., 'compact', 'midnight-js', 'example-counter')"),
+    path: z.string().describe("File path within repository"),
+    ref: z
+        .string()
+        .optional()
+        .describe("Branch, tag, or commit SHA (default: main)"),
+});
+export const ListExamplesInputSchema = z.object({
+    category: z
+        .enum(["counter", "bboard", "token", "voting", "all"])
+        .optional()
+        .default("all")
+        .describe("Filter by example type"),
+});
+export const GetLatestUpdatesInputSchema = z.object({
+    since: z
+        .string()
+        .optional()
+        .describe("ISO date to fetch updates from (default: last 7 days)"),
+    repos: z
+        .array(z.string())
+        .optional()
+        .describe("Specific repos to check (default: all configured repos)"),
+});
+export const GetVersionInfoInputSchema = z.object({
+    repo: z.string().describe("Repository name (e.g., 'compact', 'midnight-js')"),
+});
+export const CheckBreakingChangesInputSchema = z.object({
+    repo: z.string().describe("Repository name (e.g., 'compact', 'midnight-js')"),
+    currentVersion: z
+        .string()
+        .describe("Version you're currently using (e.g., 'v1.0.0', '0.5.2')"),
+});
+export const GetMigrationGuideInputSchema = z.object({
+    repo: z.string().describe("Repository name (e.g., 'compact', 'midnight-js')"),
+    fromVersion: z.string().describe("Version you're migrating from"),
+    toVersion: z
+        .string()
+        .optional()
+        .describe("Target version (default: latest stable)"),
+});
+export const GetFileAtVersionInputSchema = z.object({
+    repo: z.string().describe("Repository name (e.g., 'compact', 'midnight-js')"),
+    path: z.string().describe("File path within repository"),
+    version: z
+        .string()
+        .describe("Version tag (e.g., 'v1.0.0') or branch (e.g., 'main')"),
+});
+export const CompareSyntaxInputSchema = z.object({
+    repo: z.string().describe("Repository name (e.g., 'compact')"),
+    path: z.string().describe("File path to compare"),
+    oldVersion: z.string().describe("Old version tag (e.g., 'v0.9.0')"),
+    newVersion: z
+        .string()
+        .optional()
+        .describe("New version tag (default: latest)"),
+});
+export const GetLatestSyntaxInputSchema = z.object({
+    repo: z
+        .string()
+        .default("compact")
+        .describe("Repository name (default: 'compact')"),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/tools/repository/tools.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repository tool definitions
+ * MCP tool registration for repository-related operations
+ */
+import type { ExtendedToolDefinition } from "../../types/index.js";
+export declare const repositoryTools: ExtendedToolDefinition[];
+//# sourceMappingURL=tools.d.ts.map