@bridgetek/pre820-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,170 @@
+# @bridgetek/pre820-mcp-server
+
+MCP server for AI-assisted PRE820 and EveApps development.
+
+`@bridgetek/pre820-mcp-server` provides a local Model Context Protocol (MCP) server that enables AI coding assistants to interact with PRE820/EveApps development resources.
+
+It uses `@bridgetek/pre820-eveapps-core` as the underlying engine for:
+
+- API and command lookup
+- Sample discovery
+- Knowledge retrieval
+- Ranking and search
+- PRE820/EVE development assistance workflows
+
+The server works with a local EveApps repository checkout to provide project-aware development support.
+
+## Installation
+
+Install from npm:
+
+```
+npm install -g @bridgetek/pre820-mcp-server
+```
+
+Verify installation:
+
+```
+pre820-mcp-server --help
+```
+
+## Quick start
+
+Start the MCP server with your local EveApps repository:
+
+```
+pre820-mcp-server --eveapps /path/to/EveApps-repository
+```
+
+If `--eveapps` is not provided, the current working directory will be used.
+
+The server can then be configured as an MCP server in compatible AI development tools such as Claude Code.
+
+Example:
+
+```
+{
+  "mcpServers": {
+    "pre820": {
+      "command": "pre820-mcp-server",
+      "args": [
+        "--eveapps",
+        "/path/to/EveApps-repository"
+      ]
+    }
+  }
+}
+```
+
+## Command line options
+
+|Option|Description|
+|------|-----------|
+|--eveapps <path>|Path to a local EveApps repository used for source search and development assistance|
+|--help, -h|Display command usage information|
+
+## Features
+
+The MCP server provides AI-assisted workflows for PRE820/EVE development, including:
+
+- Finding relevant PRE820/EVE samples
+- Searching API commands and registers
+- Retrieving development guidance
+- Mapping requirements to existing examples
+- Supporting code generation and validation workflows
+
+## Relationship with pre820-eveapps-core
+
+This package provides the MCP integration layer.
+
+The underlying retrieval and indexing functionality is provided by:
+
+`@bridgetek/pre820-eveapps-core`
+
+Architecture:
+
+```
+AI Assistant
+      |
+      v
+pre820-mcp-server
+      |
+      v
+pre820-eveapps-core
+      |
+      v
+EveApps repository + indexes
+```
+
+## Development
+
+- Source entry: `packages/pre820-mcp-server/src/server.ts` (TypeScript).
+- TypeScript path mapping uses the local `@bridgetek/pre820-eveapps-core` source for fast development. See `packages/pre820-mcp-server/tsconfig.json`.
+
+Build from the monorepo root:
+
+```sh
+# Install dependencies:
+npm install
+
+# Build all packages:
+npm run build
+
+# Or build only the MCP server:
+npm --prefix packages/pre820-mcp-server run build
+
+# Run the built server:
+node packages/pre820-mcp-server/dist/cli.js --eveapps /path/to/EveApps-repository
+```
+
+## Publishing
+
+This package is scoped to the `@bridgetek` organization and is published publicly. Typical publish flow:
+
+```bash
+cd packages/pre820-eveapps-core
+npm publish --access public
+
+cd ../pre820-mcp-server
+# ensure core is published first (or available in registry)
+npm publish --access public
+```
+
+> [!NOTE]
+> - `@bridgetek/pre820-eveapps-core` should be published before publishing this package.
+> - The package is configured as a public scoped npm package.
+> - If the scoped package already exists, bump `version` before publishing: `npm version patch`.
+> - If npm account security requires two-factor authentication, an OTP will be required during publishing.
+
+## Troubleshooting
+
+### Cannot resolve pre820-eveapps-core
+
+If running from a local development checkout, link both packages:
+
+```bash
+npm --prefix packages/pre820-eveapps-core link
+npm --prefix packages/pre820-mcp-server link
+```
+
+### Build issues
+
+Make sure dependencies are installed from the repository root:
+
+```
+npm install
+```
+
+Then rebuild:
+
+```
+npm run build
+```
+
+## License
+
+See repository `LICENSE.md`.
+
+## Maintainers
+
+BridgeTek engineering team

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./server.js";

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./server.js";
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,181 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createWorkspaceContext, generateBuildCommand, generateBuildCommandInput, findRelevantSample, findRelevantSampleInput, explainEveSymbol, explainEveSymbolInput, generateScreenScaffold, generateScreenScaffoldInput, validatePre820Code, validatePre820CodeInput, traceFeatureToCommands, traceFeatureToCommandsInput, readSourceFile, readSourceFileInput, lookupModuleGraphics, lookupModuleGraphicsInput, retrieveAnswer } from "@bridgetek/pre820-eveapps-core";
+// -----------------------------
+// Workspace handling
+// -----------------------------
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--eveapps") {
+            args.eveappsRoot = argv[i + 1];
+        }
+    }
+    return args;
+}
+function printUsage() {
+    console.log(`Usage: node server.js [--eveapps <path>]
+
+Options:
+  --eveapps <path>    Path to the local EveApps repository
+  --help, -h          Show this help message
+`);
+}
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    printUsage();
+    process.exit(0);
+}
+// EveApps separation (future-proof)
+const args = parseArgs(process.argv);
+const eveappsRoot = args.eveappsRoot ?? process.cwd();
+// Context object passed to core
+const context = createWorkspaceContext(eveappsRoot);
+// -----------------------------
+// MCP Server
+// -----------------------------
+const server = new McpServer({
+    name: "pre820-mcp-server",
+    version: "1.0.0"
+}, {
+    capabilities: {
+        tools: {}
+    }
+});
+function safeTool(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            console.error("[PRE820 MCP ERROR]", err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: err.message ?? String(err)
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+    };
+}
+// -----------------------------
+// Primary PRE820 engineering AI tool
+// -----------------------------
+server.registerTool("ask_pre820", {
+    title: "Primary PRE820 and EveApps Engineering Assistant",
+    description: "Authoritative local PRE820 engineering assistant. " +
+        "Uses indexed PRE820 knowledge plus direct source-code " +
+        "search over the local EveApps repository configured " +
+        "through --eveapps. " +
+        "Use this tool FIRST for all PRE820, EveApps, EVE graphics, " +
+        "display pipeline, rendering, widget, command buffer, " +
+        "register, sample project, build system, SPI, display timing, " +
+        "platform porting, UI generation, API usage, and debugging questions. " +
+        "Treat EVE_CoDl_xxx helpers and corresponding XXX macros, and EVE_CoCmd_xxx " +
+        "helpers and corresponding CMD_XXX tokens from EVE_GpuDefs.h, as equivalent " +
+        "during retrieval and usage analysis. Prefer EVE_CoDl_xxx and EVE_CoCmd_xxx " +
+        "helpers in generated application code unless a packed or intentionally low-level command word is required. " +
+        "This tool searches the user's LOCAL EveApps source tree and " +
+        "returns concrete source file matches, sample references, " +
+        "commands, and implementation details before external web search.",
+    inputSchema: z.object({
+        query: z.string().describe("Natural language PRE820/EveApps engineering question")
+    }).shape
+}, safeTool(async (args) => {
+    const result = await retrieveAnswer(context, args.query);
+    // Strengthen Claude confidence with explicit wording
+    return {
+        ...result,
+        retrieval_context: {
+            local_repo_enabled: !!context.eveappsRoot,
+            local_repo: context.eveappsRoot ?? null,
+            retrieval_priority: [
+                "pre820-eveapps-core index",
+                "local EveApps source repository",
+                "metadata ranking"
+            ],
+            symbol_policy: {
+                equivalent_for_search: true,
+                generated_code_preference: "EVE_CoDl_* and EVE_CoCmd_* helpers",
+                raw_macros_allowed_for: [
+                    "packed display-list word construction",
+                    "display-list command arrays",
+                    "coprocessor command-buffer arrays",
+                    "intentional low-level EVE_Cmd_wr32 paths"
+                ]
+            },
+            note: "Results were generated from local PRE820/EveApps " +
+                "engineering resources before considering external sources."
+        }
+    };
+}));
+// -----------------------------
+// Legacy tools (unchanged behavior)
+// -----------------------------
+server.registerTool("generate_build_command", {
+    title: "Generate validated PRE820 build command",
+    description: "Generate a validated build command for PRE820/EVE targets.",
+    inputSchema: generateBuildCommandInput.shape,
+}, safeTool(generateBuildCommand));
+server.registerTool("find_relevant_sample", {
+    title: "Find relevant EveApps sample",
+    description: "Find the most relevant EveApps sample for the provided request.",
+    inputSchema: findRelevantSampleInput.shape,
+}, safeTool(findRelevantSample));
+server.registerTool("explain_eve_symbol", {
+    title: "Explain PRE820/EVE symbol",
+    description: "Explain a PRE820/EVE helper or GPU macro, including canonical EVE_CoDl and EVE_CoCmd helpers. Prefer helpers over raw XXX and CMD_XXX macros in generated application code.",
+    inputSchema: explainEveSymbolInput.shape,
+}, safeTool(explainEveSymbol));
+server.registerTool("generate_screen_scaffold", {
+    title: "Generate screen scaffold",
+    description: "Generate a PRE820 screen scaffold from inputs.",
+    inputSchema: generateScreenScaffoldInput.shape,
+}, safeTool(generateScreenScaffold));
+server.registerTool("validate_pre820_code", {
+    title: "Validate PRE820 code for issues",
+    description: "Validate PRE820/EVE code and recommend EVE_CoDl or EVE_CoCmd helpers for equivalent raw GPU macros, while allowing intentional packed command usage.",
+    inputSchema: validatePre820CodeInput.shape,
+}, safeTool(validatePre820Code));
+server.registerTool("trace_feature_to_commands", {
+    title: "Trace feature to PRE820 commands",
+    description: "Trace feature usage to commands.",
+    inputSchema: traceFeatureToCommandsInput.shape,
+}, safeTool(traceFeatureToCommands));
+server.registerTool("pre820_read_file", {
+    title: "Read raw source file",
+    description: "Read the raw contents of a file from the local EveApps repository.",
+    inputSchema: readSourceFileInput.shape,
+}, safeTool(async (args) => readSourceFile(args, context)));
+server.registerTool("lookup_module_graphics", {
+    title: "Lookup module and graphics metadata",
+    description: "Resolve module codes and graphics chip metadata from the local PRE820 indexes.",
+    inputSchema: lookupModuleGraphicsInput.shape,
+}, safeTool(lookupModuleGraphics));
+// -----------------------------
+// Startup diagnostics (VERY IMPORTANT for EXE)
+// -----------------------------
+console.error("===================================");
+console.error("PRE820 MCP Server Starting...");
+console.error("eveappsRoot:", eveappsRoot ?? "NOT SET");
+console.error("Node:", process.version);
+console.error("===================================");
+// -----------------------------
+// Start transport
+// -----------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("PRE820 MCP Server running...");
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@bridgetek/pre820-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/server.js",
+  "bin": {
+    "@bridgetek/pre820-mcp-server": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.1",
+    "@bridgetek/pre820-eveapps-core": "^1.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.10"
+  }
+}