esp-modkit 0.1.0

data/lib/esp/mcp_server.rb

@@ -0,0 +1,465 @@
+require 'json'
+
+module Esp
+  # Model Context Protocol server over stdio, so AI assistants (Claude Code,
+  # Claude Desktop, …) can author, build, lint, and query a mod project as
+  # native tools. It is a thin shell over Esp::Operations — the same service
+  # layer the HTTP API uses — so every tool returns the same payload the CLI
+  # `--json` mode and `esp serve` already emit.
+  #
+  # Transport is the MCP stdio convention: newline-delimited JSON-RPC 2.0,
+  # one message per line, no embedded newlines. Requests carry an `id` and
+  # get a response; notifications (no `id`) get none. The protocol stream
+  # owns stdout, so all diagnostics go to stderr.
+  #
+  # Operation errors (missing mod, no index, bad source) come back as a
+  # tool result with `isError: true` — the model sees the message and can
+  # recover. Only malformed protocol traffic (bad JSON, unknown method,
+  # unknown tool) uses a JSON-RPC error response.
+  #
+  # Alongside tools, the server exposes read-only **resources**
+  # (`resources/list` + `resources/read`): the command-tree introspection
+  # and the narrative docs, so an agent can pull context without a tool call.
+  class McpServer
+    PROTOCOL_VERSION = '2024-11-05'.freeze
+
+    # Each tool maps an MCP tool name to an Esp::Operations method plus the
+    # JSON Schema the client uses to build calls. `arguments` arrive as a
+    # string-keyed hash, exactly the shape Operations expects.
+    TOOLS = [
+      {
+        name: 'version',
+        description: 'Print the esp toolchain version.',
+        input_schema: { type: 'object', properties: {}, additionalProperties: false },
+        op: :version
+      },
+      {
+        name: 'commands',
+        description: 'Discover the full esp command tree — names, usage, and options.',
+        input_schema: { type: 'object', properties: {}, additionalProperties: false },
+        op: :commands
+      },
+      {
+        name: 'open_project',
+        description: 'Point the server at a project directory. Validates the path + the project ' \
+                     'marker\'s game id; every subsequent op runs against this root until a new ' \
+                     'open_project request or an explicit `root:` overrides it.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            root: { type: 'string', description: 'Absolute path to a directory (esp init creates one).' }
+          },
+          required: ['root'],
+          additionalProperties: false
+        },
+        op: :open_project
+      },
+      {
+        name: 'active_project',
+        description: 'The project currently active on the server (root + game). Returns nulls if no ' \
+                     'open_project has happened yet.',
+        input_schema: { type: 'object', properties: {}, additionalProperties: false },
+        op: :active_project
+      },
+      {
+        name: 'projects_recent',
+        description: 'Recently-opened projects, newest-first. Persisted per user (ESP_DATA_DIR).',
+        input_schema: { type: 'object', properties: {}, additionalProperties: false },
+        op: :projects_recent
+      },
+      {
+        name: 'projects_new',
+        description: 'Scaffold a brand-new project (git init + .esp/project.json + first mod) under ' \
+                     "the user's mods_home. Same flow ESPresso's \"New Project\" runs.",
+        input_schema: {
+          type: 'object',
+          properties: {
+            project: { type: 'string', description: 'Project name (becomes the directory name).' },
+            mod: { type: 'string', description: 'Name of the first mod to scaffold inside it.' },
+            game: { type: 'string', description: "Game plugin id (default: 'mw')." },
+            format: { type: 'string', enum: %w[json rb py js mjs ts],
+                      description: 'First mod source format (default: json).' },
+            author: { type: 'string', description: 'Author for the scaffolded mod header.' },
+            description: { type: 'string', description: 'Description for the scaffolded mod header.' }
+          },
+          required: %w[project mod],
+          additionalProperties: false
+        },
+        op: :projects_new
+      },
+      {
+        name: 'build',
+        description: 'Build mods/<MOD> to dist/<MOD>[.locale].esp via tes3conv.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            mod: { type: 'string', description: 'Mod name (folder under mods/).' },
+            locale: { type: 'string', description: 'Optional locale; output becomes <MOD>.<locale>.esp.' }
+          },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :build
+      },
+      {
+        name: 'build_all',
+        description: 'Build every mod under mods/ to dist/. Returns one result per mod.',
+        input_schema: {
+          type: 'object',
+          properties: { locale: { type: 'string', description: 'Optional locale applied to every build.' } },
+          additionalProperties: false
+        },
+        op: :build_all
+      },
+      {
+        name: 'unpack',
+        description: 'Import an existing plugin (.esp/.esm/.omwaddon) into mods/<NAME>/<NAME>.json.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            plugin: { type: 'string', description: 'Plugin path or installed plugin name (Fargoth.esp).' },
+            name: { type: 'string', description: 'Mod folder name (default: plugin basename).' },
+            config: { type: 'string', description: 'openmw.cfg to resolve a bare name against (optional).' }
+          },
+          required: ['plugin'],
+          additionalProperties: false
+        },
+        op: :unpack
+      },
+      {
+        name: 'install',
+        description: 'Make a built dist/<MOD>.esp available to the game. Default: register with ' \
+                     'openmw.cfg. Set copy_to or to_data_files to also copy the plugin into the ' \
+                     'vanilla Data Files dir for the original engine.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            mod: { type: 'string', description: 'Mod name; built .esp must exist in dist/.' },
+            copy_to: { type: 'string',
+                       description: 'Also copy the .esp into this directory (original engine).' },
+            to_data_files: { type: 'boolean',
+                             description: 'Also copy to the auto-detected Morrowind Data Files dir.' },
+            register_openmw: { type: 'boolean',
+                               description: 'Register with openmw.cfg (default true).' }
+          },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :install
+      },
+      {
+        name: 'plugins_list',
+        description: 'List plugins OpenMW has installed (from openmw.cfg) with active flag + load order.',
+        input_schema: {
+          type: 'object',
+          properties: { config: { type: 'string', description: 'Path to openmw.cfg (optional).' } },
+          additionalProperties: false
+        },
+        op: :plugins_list
+      },
+      {
+        name: 'i18n_check',
+        description: 'Report missing/orphan i18n keys per locale for a mod (vs. the default en catalogue).',
+        input_schema: {
+          type: 'object',
+          properties: { mod: { type: 'string', description: 'Mod name (folder under mods/).' } },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :i18n_check
+      },
+      {
+        name: 'lint',
+        description: 'Check a mod for dangling refs and missing-master issues against the reference index.',
+        input_schema: {
+          type: 'object',
+          properties: { mod: { type: 'string', description: 'Mod name (folder under mods/).' } },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :lint
+      },
+      {
+        name: 'scaffold',
+        description: 'Create a new mod folder under mods/<MOD>/ with a starter source file and README.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            mod: { type: 'string', description: 'Mod name to create.' },
+            format: { type: 'string', enum: %w[json rb py js mjs ts], description: 'Format; default json.' },
+            author: { type: 'string', description: 'Author name (default: git config user.name).' },
+            description: { type: 'string', description: 'Plugin description.' },
+            force: { type: 'boolean', description: 'Overwrite an existing mod folder.' }
+          },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :scaffold
+      },
+      {
+        name: 'extract_scripts',
+        description: "Hoist each Script record's inline text into mods/<MOD>/scripts/<id>.mwscript.",
+        input_schema: {
+          type: 'object',
+          properties: { mod: { type: 'string', description: 'Mod name (folder under mods/).' } },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :extract_scripts
+      },
+      {
+        name: 'refs_find',
+        description: 'Search the vanilla reference index — substring match on id + name by default.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            q: { type: 'string', description: 'Substring to match against record id and name.' },
+            type: { type: 'string', description: 'Filter by record type (e.g. Npc, Cell, Script).' },
+            like: { type: 'string', description: "SQL LIKE pattern on id (e.g. 'Fargoth%')." },
+            exact: { type: 'boolean', description: 'Match q as an exact id instead of a substring.' },
+            show: { type: 'boolean', description: 'Return the full JSON record for each match.' },
+            limit: { type: 'integer', description: 'Max rows to return (default 100).' }
+          },
+          additionalProperties: false
+        },
+        op: :refs_find
+      },
+      {
+        name: 'records_read',
+        description: "Read a mod's records as structured data (works for any source format).",
+        input_schema: {
+          type: 'object',
+          properties: { mod: { type: 'string', description: 'Mod name (folder under mods/).' } },
+          required: ['mod'],
+          additionalProperties: false
+        },
+        op: :records_read
+      },
+      {
+        name: 'record_write',
+        description: "Insert/update one record in a mod's .json source, keyed by type+id (JSON only).",
+        input_schema: {
+          type: 'object',
+          properties: {
+            mod: { type: 'string', description: 'Mod name (folder under mods/).' },
+            record: { type: 'object', description: 'TES3 record; needs "type" (+ "id" unless Header).' }
+          },
+          required: %w[mod record],
+          additionalProperties: false
+        },
+        op: :record_write
+      },
+      {
+        name: 'dialogue_write',
+        description: "Author dialogue from a JSON spec into a mod's .json source (data-driven Dialogue " \
+                     'DSL). A topic is replaced wholesale, so re-authoring leaves no orphan info records. ' \
+                     'Info filters mirror the DSL (speaker/race/class/faction/cell/sex/pc_faction/pc_rank/' \
+                     'speaker_rank/disposition/sound/result_script/journal_index); @t:key in text for i18n.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            mod: { type: 'string', description: 'Mod name (folder under mods/).' },
+            spec: {
+              type: 'object',
+              properties: {
+                topics: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      name: { type: 'string' },
+                      type: { type: 'string', enum: %w[topic journal greeting persuasion voice] },
+                      speaker: { type: 'string' },
+                      infos: {
+                        type: 'array',
+                        items: { type: 'object', properties: { text: { type: 'string' } } }
+                      }
+                    },
+                    required: %w[name infos]
+                  }
+                }
+              },
+              required: ['topics']
+            }
+          },
+          required: %w[mod spec],
+          additionalProperties: false
+        },
+        op: :dialogue_write
+      }
+    ].freeze
+
+    TOOLS_BY_NAME = TOOLS.to_h { |t| [t[:name], t] }.freeze
+
+    # Narrative docs exposed as resources, by slug under docs/.
+    DOC_PAGES = [
+      ['walkthrough',     'Walkthrough',      'End-to-end: a plugin from empty to built.'],
+      ['getting-started', 'Getting started',  'Install, macOS paths, wiring mw into an AI client.'],
+      ['authoring-guide', 'Authoring guide',  'Source formats, scripts, dialogue DSL, i18n, linting.'],
+      ['architecture',    'Architecture',     'Layered design and the roadmap.']
+    ].freeze
+
+    # Read-only context an agent can pull without a tool call: the command
+    # tree (same payload as the `commands` tool) and the narrative docs.
+    # Each :read lambda produces the resource body on demand.
+    RESOURCES = ([
+      { uri: 'mw://introspection', name: 'mw command tree',
+        description: 'Full command tree, options, and module surface.',
+        mime_type: 'application/json',
+        read: -> { JSON.pretty_generate(Esp::Introspection.command_tree) } }
+    ] + DOC_PAGES.map do |slug, name, description|
+      { uri: "mw://docs/#{slug}", name: name, description: description, mime_type: 'text/markdown',
+        read: -> { File.read(File.join(Esp::ROOT, 'docs', "#{slug}.md")) } }
+    end).freeze
+
+    RESOURCES_BY_URI = RESOURCES.to_h { |r| [r[:uri], r] }.freeze
+
+    # JSON-RPC error codes (subset of the spec we actually emit).
+    PARSE_ERROR = -32_700
+    INVALID_REQUEST = -32_600
+    METHOD_NOT_FOUND = -32_601
+    INVALID_PARAMS = -32_602
+    INTERNAL_ERROR = -32_603
+
+    # Caller-fault errors surfaced as a tool result rather than a protocol
+    # error — the shared list Operations owns.
+    TOOL_ERRORS = Esp::Operations.caller_errors
+
+    # Raised internally to carry a JSON-RPC error code out to the responder.
+    class ProtocolError < StandardError
+      attr_reader :code
+
+      def initialize(code, message)
+        super(message)
+        @code = code
+      end
+    end
+
+    def initialize(input: $stdin, output: $stdout)
+      @input = input
+      @output = output
+    end
+
+    # Read JSON-RPC messages line by line until stdin closes. Each line is a
+    # complete message; blank lines are ignored.
+    def start
+      @input.each_line do |line|
+        line = line.strip
+        next if line.empty?
+
+        response = process(line)
+        write(response) if response
+      end
+    end
+
+    private
+
+    def process(line)
+      message = JSON.parse(line)
+    rescue JSON::ParserError
+      error_response(nil, PARSE_ERROR, 'parse error')
+    else
+      handle(message)
+    end
+
+    def handle(message)
+      raise ProtocolError.new(INVALID_REQUEST, 'invalid request') unless message.is_a?(Hash)
+
+      id = message['id']
+      result = dispatch(message['method'], message['params'] || {}, id)
+      id.nil? ? nil : success_response(id, result)
+    rescue ProtocolError => e
+      error_response(message_id(message), e.code, e.message)
+    rescue StandardError => e
+      error_response(message_id(message), INTERNAL_ERROR, e.message)
+    end
+
+    # Returns the result for a known method. Unknown methods raise
+    # METHOD_NOT_FOUND for requests but are silently dropped for
+    # notifications (no id), per JSON-RPC.
+    def dispatch(method, params, id)
+      case method
+      when 'initialize'                then initialize_result
+      when 'tools/list'                then { tools: tool_descriptors }
+      when 'tools/call'               then call_tool(params)
+      when 'resources/list'           then { resources: resource_descriptors }
+      when 'resources/templates/list' then { resourceTemplates: [] }
+      when 'resources/read'           then read_resource(params)
+      when 'ping'                     then {}
+      when %r{\Anotifications/}       then nil # fire-and-forget, no response
+      else
+        raise ProtocolError.new(METHOD_NOT_FOUND, "method not found: #{method}") unless id.nil?
+
+        nil
+      end
+    end
+
+    def initialize_result
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {}, resources: {} },
+        serverInfo: { name: 'esp', version: Esp::VERSION }
+      }
+    end
+
+    def tool_descriptors
+      TOOLS.map do |tool|
+        { name: tool[:name], description: tool[:description], inputSchema: tool[:input_schema] }
+      end
+    end
+
+    def resource_descriptors
+      RESOURCES.map do |r|
+        { uri: r[:uri], name: r[:name], description: r[:description], mimeType: r[:mime_type] }
+      end
+    end
+
+    def read_resource(params)
+      uri = params['uri']
+      resource = RESOURCES_BY_URI[uri]
+      raise ProtocolError.new(INVALID_PARAMS, "unknown resource: #{uri}") unless resource
+
+      { contents: [{ uri: uri, mimeType: resource[:mime_type], text: resource[:read].call }] }
+    end
+
+    def call_tool(params)
+      name = params['name']
+      tool = TOOLS_BY_NAME[name]
+      raise ProtocolError.new(INVALID_PARAMS, "unknown tool: #{name}") unless tool
+
+      payload = Esp::Operations.dispatch(tool[:op], params['arguments'] || {})
+      tool_result(payload)
+    rescue *TOOL_ERRORS => e
+      tool_error(e)
+    end
+
+    def tool_result(payload)
+      { content: [{ type: 'text', text: JSON.pretty_generate(payload) }] }
+    end
+
+    # Structured tool error: the text content is a JSON object carrying a
+    # stable code + message, so an agent can branch on the code rather than
+    # parse prose. isError tells the client the call failed but is recoverable.
+    def tool_error(exception)
+      payload = { error: { code: Esp::Operations.error_code(exception), message: exception.message } }
+      { content: [{ type: 'text', text: JSON.pretty_generate(payload) }], isError: true }
+    end
+
+    def success_response(id, result)
+      { jsonrpc: '2.0', id: id, result: result }
+    end
+
+    def error_response(id, code, message)
+      { jsonrpc: '2.0', id: id, error: { code: code, message: message } }
+    end
+
+    def message_id(message)
+      message.is_a?(Hash) ? message['id'] : nil
+    end
+
+    def write(response)
+      @output.puts(JSON.generate(response))
+      @output.flush
+    end
+  end
+end

data/lib/esp/mw/builder.rb

@@ -0,0 +1,71 @@
+require 'fileutils'
+require 'json'
+require 'tempfile'
+
+module Esp
+  module Mw
+    # Orchestrates mods/<Mod>/<Mod>.json -> dist/<Mod>.esp:
+    #   1. Load source JSON.
+    #   2. Run Esp::Mw::Preflight to inline text_source files and regenerate
+    #      Script record blobs.
+    #   3. Hand the canonical JSON to tes3conv via a tempfile (whose
+    #      extension must be .json — tes3conv sniffs by extension).
+    module Builder
+      Result = Struct.new(:output, :logs, keyword_init: true)
+
+      class << self
+        def build(mod, root: Esp::ROOT, locale: nil)
+          source = Esp::Mw::Loader.resolve(mod, root: root)
+          source_dir = File.dirname(source)
+
+          i18n = build_i18n(source_dir, locale)
+          records = Esp::Mw::Loader.load(source, i18n: i18n)
+          i18n.resolve!(records)
+
+          logs = Esp::Mw::Preflight.process!(records, source_dir: source_dir)
+          logs.concat(i18n_miss_logs(i18n))
+
+          output = output_path(mod, root, locale: locale)
+          FileUtils.mkdir_p(File.dirname(output))
+
+          Tempfile.create(['mw-build-', '.json']) do |tmp|
+            tmp.write("#{JSON.pretty_generate(records)}\n")
+            tmp.close
+            Esp::Mw::Tes3conv.convert(tmp.path, output)
+          end
+
+          Result.new(output: output, logs: logs)
+        end
+
+        def output_path(mod, root, locale: nil)
+          name = locale ? "#{mod}.#{locale}" : mod
+          File.join(root, 'dist', "#{name}.esp")
+        end
+
+        def discover_mods(root: Esp::ROOT)
+          Dir.glob(File.join(root, 'mods', '*')).filter_map do |dir|
+            next unless File.directory?(dir)
+
+            name = File.basename(dir)
+            unless Esp::Mw::Loader.supported_exts.any? { |ext| File.exist?(File.join(dir, "#{name}#{ext}")) }
+              next
+            end
+
+            name
+          end
+        end
+
+        private
+
+        def build_i18n(source_dir, locale)
+          catalogues = Esp::Mw::I18n.load_catalogues(source_dir)
+          Esp::Mw::I18n.new(catalogues, locale: locale || Esp::Mw::I18n::DEFAULT_LOCALE)
+        end
+
+        def i18n_miss_logs(i18n)
+          i18n.misses.map { |m| "i18n: missing key #{m.key.inspect} in locale #{m.locale.inspect}" }
+        end
+      end
+    end
+  end
+end

data/lib/esp/mw/data_files.rb

@@ -0,0 +1,67 @@
+module Esp
+  module Mw
+    # Where Morrowind keeps its vanilla data files (`Morrowind.esm` and
+    # friends, plus user-installed `.esp` plugins for the original engine).
+    # Engine-agnostic — OpenMW reads them via `data=` in openmw.cfg; the
+    # original engine reads them in place. The same set of probe paths
+    # serves both:
+    #
+    # - `esp refs unpack` reads the vanilla ESMs out of here.
+    # - `esp install --to-data-files` copies a built plugin into here so
+    #   the original engine's launcher picks it up.
+    #
+    # Detection is best-effort, per-OS Steam/GOG defaults. Anything
+    # non-default is overridable via $MORROWIND_DATA or an explicit flag.
+    module DataFiles
+      class << self
+        def candidates
+          home = Dir.home
+          case Esp::Mw::OpenmwConfig.host_os
+          when :macos   then macos_candidates(home)
+          when :windows then windows_candidates
+          else               linux_candidates(home)
+          end
+        end
+
+        # The first existing candidate, else the first candidate (so error
+        # messages can still name a reasonable path even when nothing's
+        # installed).
+        def default
+          candidates.find { |dir| File.directory?(dir) } || candidates.first
+        end
+
+        # Resolve the user's intent: --data override beats $MORROWIND_DATA
+        # beats the per-OS default. Returns the resolved path (no validation
+        # — the caller decides whether to error on a missing dir).
+        def resolve(override: nil)
+          return override if override && !override.to_s.empty?
+          return ENV['MORROWIND_DATA'] if ENV['MORROWIND_DATA'] && !ENV['MORROWIND_DATA'].empty?
+
+          default
+        end
+
+        private
+
+        def macos_candidates(home)
+          steam = "#{home}/Library/Application Support/Steam/steamapps/common"
+          ["#{steam}/The Elder Scrolls III - Morrowind/Data Files",
+           "#{steam}/Morrowind/Data Files"]
+        end
+
+        def windows_candidates
+          ['C:/Program Files (x86)/Steam/steamapps/common/Morrowind/Data Files',
+           'C:/GOG Games/Morrowind/Data Files',
+           'C:/Program Files (x86)/GOG Galaxy/Games/Morrowind/Data Files',
+           'C:/Program Files/Bethesda Softworks/Morrowind/Data Files']
+        end
+
+        def linux_candidates(home)
+          ["#{home}/.steam/steam/steamapps/common/Morrowind/Data Files",
+           "#{home}/.local/share/Steam/steamapps/common/Morrowind/Data Files",
+           "#{home}/Documents/Games/Morrowind/app/Data Files",
+           "#{home}/.wine/drive_c/Program Files/Bethesda Softworks/Morrowind/Data Files"]
+        end
+      end
+    end
+  end
+end