simple_english 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c669ec0be5be6b79c011236f4f54137d399e4b8be06ead9a20ca2e2ea0f683
-  data.tar.gz: 6a67aa7cf3cab9a5187911ca40de39f1366ed11e80bee913b32527f5c376fc9f
+  metadata.gz: 8021741a0615e3d936a8a9bdabe7579fb1fa9641ce5061bf2d3a0e2bb24dd4d9
+  data.tar.gz: 87fb729f7e72ef9af5d3c63b305fdff9bea3b3aec034429ac52eaffb54639559
 SHA512:
-  metadata.gz: '078dc707335ac5a3b0e9b48054ba308c1d32c91b8ef9d3f5f37c577907e4cd74a121c8a221a5c8a829e762204e2f1a72a6e52090f0fded27b256b892fbdb0d68'
-  data.tar.gz: b6f84dea9be787d81e0206c11219350ba7113ba53f44d222ceab1b4c0a1f87d98c53d5c0344164a0287f988d7c9fb7d7b22894a63b8573ceb619279a62fe3a2d
+  metadata.gz: '058e1303247e2ca2aee046e1ff1c9341ff96fae26f4c4fcbb67410cd7652d0d806be163c0abb7c393ce81a725bc8b94a0a4faaeee09c89d8f04daf738a7dd677'
+  data.tar.gz: 57e8431a0c71e31a3f14d3ab6f776dfe10e0f49f60a279c7b0d4a53f7d432594a4d79af76700cc6fbc45b26767258eca3a957817cd8574f05fd64c4cff09f223

data/README.md

@@ -214,6 +214,19 @@ verifies. Closing the Vale gaps needs scripts or an external
 tagger, and that erases Vale's main advantage: one binary with no
 service behind it.
 
+## Agent integrations
+
+Pi, Claude Code, and Codex can lint the prose they write. The adapters
+live under `integrations/`, unreleased. Try them from a checkout:
+
+```bash
+claude --plugin-dir integrations/claude-code   # the hook feeds findings back
+pi install integrations/pi -l                  # the se_lint tool
+se mcp                                         # an MCP server, for any MCP client
+```
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full story.
+
 ## Develop
 
 To change the linter, add rules, or run the tests, read [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

data/lib/simple_english/cli.rb

@@ -20,7 +20,11 @@ module SimpleEnglish
           (first == "-" || !first.start_with?("-"))
         given_args = ["lint", *given_args]
       end
-      super
+      # Thor's own commands (help, tree) return junk like nil or a
+      # Hash, not an exit status. Contract: start always returns an
+      # Integer so every caller (bin/se, tests) can exit on it.
+      status = super
+      status.is_a?(Integer) ? status : 0
     end
 
     # The test entry point. It keeps the old module interface.
@@ -72,6 +76,12 @@ module SimpleEnglish
       0
     end
 
+    desc "mcp", "Run the MCP stdio server (one JSON-RPC message per line)"
+    def mcp
+      SimpleEnglish::ModelContextProtocol.run
+      0
+    end
+
     desc "serve", "Run the lint daemon in the foreground"
     method_option :port, type: :numeric, default: SimpleEnglish::Client::DEFAULT_PORT,
       desc: "Port to listen on"
@@ -89,7 +99,7 @@ module SimpleEnglish
           return 0
         end
         warn "error: detached daemon did not come up. " \
-          "Run `se serve` and read its output."
+          "Run `#{Client.runner} serve` and read its output."
         return 2
       end
       log = options[:"dev-log"] ? File.open(options[:"dev-log"], "w") : $stderr
@@ -128,11 +138,22 @@ module SimpleEnglish
     # "-" stays as-is for stdin. Directories expand to all lintable files.
     # Glob output keeps a "./" prefix when the argument is ".". Strip it so
     # paths and config ignore globs always see the same form.
+    # These trees hold third-party prose, not the user's. The tool lints
+    # what the user owns. Skipped only during directory expansion. An
+    # explicit path always lints.
+    # Dir.glob never returns dotfiles, so ".git" is inert today. It
+    # guards a future FNM_DOTMATCH from turning git internals back on.
+    # .gitignore is not read. Users put ignore: globs in the config for
+    # build output and generated files.
+    SKIPPED_DIRS = [".git", "node_modules", "vendor"].freeze
+
     def self.expand_paths(argv)
       extensions = (SimpleEnglish::Extractor::EXTENSION_LANGUAGES.keys.map { |e| e.delete_prefix(".") } + ["md"]).uniq.join(",")
       argv.flat_map do |path|
         if File.directory?(path)
-          Dir.glob(File.join(path, "**/*.{#{extensions}}")).sort
+          Dir.glob(File.join(path, "**/*.{#{extensions}}"))
+            .reject { |p| p.split(File::SEPARATOR).any? { |s| SKIPPED_DIRS.include?(s) } }
+            .sort
         else
           path
         end
@@ -175,16 +196,7 @@ module SimpleEnglish
         )
       else
         results.each do |path, finding|
-          location = "#{path}:#{finding.line}"
-          if finding.column
-            location += ":#{finding.column}"
-            if finding.end_line && finding.end_column
-              finish = (finding.end_line == finding.line) ? finding.end_column :
-                "#{finding.end_line}:#{finding.end_column}"
-              location += "-#{finish}"
-            end
-          end
-          puts "#{location}: [#{finding.rule}] #{finding.message}"
+          puts finding.to_line(path)
         end
       end
     end

data/lib/simple_english/client/daemon.rb

@@ -19,6 +19,15 @@ module SimpleEnglish
     DEFAULT_PORT = 8181
     REQUEST_TIMEOUT = 30
 
+    # The executable that daemon advice tells you to run. Resolved
+    # from this file, so it names the code that is actually loaded:
+    # a checkout names its bin/se, a gem install names its bundled
+    # bin/se. $PROGRAM_NAME is wrong for library callers: their host
+    # script is not se.
+    def runner
+      File.expand_path("../../../bin/se", __dir__)
+    end
+
     def url
       ENV.fetch("SE_SERVER_URL") { "http://localhost:#{DEFAULT_PORT}" }
     end
@@ -113,7 +122,7 @@ module SimpleEnglish
             "It is not restarted automatically."
         else
           warn "se: daemon at #{url} is not a handshake-capable se daemon. " \
-            "Run `se serve` to replace it."
+            "Run `#{runner} serve` to replace it."
         end
         return true
       end
@@ -151,7 +160,7 @@ module SimpleEnglish
         if daemon
           check_daemon(daemon)
         else
-          warn "error: se daemon did not come up. Run `se serve` and read its output."
+          warn "error: se daemon did not come up. Run `#{runner} serve` and read its output."
           false
         end
       end
@@ -171,7 +180,7 @@ module SimpleEnglish
         return
       end
       fix = ENV["SE_SERVER_URL"] ? "It is not restarted automatically." :
-        "Run `se serve --detached` to restart it."
+        "Run `#{runner} serve --detached` to restart it."
       warn "se: daemon at #{url} runs se #{daemon["version"]}, different code than this install " \
         "(#{VERSION}). #{fix} Linting against it meanwhile."
     end

data/lib/simple_english/lint/finding.rb

@@ -5,5 +5,20 @@
 # daemon can have a start column without an end position.
 
 module SimpleEnglish
-  Finding = Struct.new(:line, :column, :end_line, :end_column, :rule, :message)
+  Finding = Struct.new(:line, :column, :end_line, :end_column, :rule, :message) do
+    # One finding as a text line: `path:line:col-end: [rule] message`.
+    # The CLI text output, the MCP tool, and the hook feedback all share
+    # this format. Keep them in step by rendering through this method.
+    def to_line(path)
+      location = "#{path}:#{line}"
+      if column
+        location += ":#{column}"
+        if end_line && end_column
+          finish = (end_line == line) ? end_column : "#{end_line}:#{end_column}"
+          location += "-#{finish}"
+        end
+      end
+      "#{location}: [#{rule}] #{message}"
+    end
+  end
 end

data/lib/simple_english/model_context_protocol.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+
+# MCP JSON-RPC server for the lint engine. `respond` is pure: request
+# Hash in, response Hash or nil (notifications) out. `run` drives it
+# over stdio, one JSON-RPC message per line. Protocol facts:
+# integrations/verification.md.
+
+module SimpleEnglish
+  module ModelContextProtocol
+    SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"].freeze
+    LATEST_VERSION = "2025-06-18"
+    SERVER_NAME = "simple-english"
+
+    module_function
+
+    def run(io: $stdin, out: $stdout, linter: method(:default_linter))
+      # A piped stdout buffers until 4 KB or EOF. An MCP client keeps
+      # stdin open while it waits for the answer, so an unflushed
+      # response never arrives and the client drops the server.
+      out.sync = true
+      while (line = io.gets)
+        line = line.strip
+        next if line.empty?
+        begin
+          request = JSON.parse(line)
+        rescue JSON::ParserError
+          next
+        end
+        next unless request.is_a?(Hash)
+        response =
+          begin
+            respond(request, linter: linter)
+          rescue => e
+            # A broken tool call (unreadable file, daemon hiccup) must not
+            # kill the loop: answer it, then serve the next line.
+            request.key?("id") ? error(request["id"], -32603, "lint failed: #{e.class}: #{e.message}") : nil
+          end
+        out.puts JSON.generate(response) if response
+      end
+    end
+
+    # The CLI's lint pipeline as a callable: .simple-english.yml decides
+    # which paths and rules count, then the daemon lints the file.
+    def default_linter(path)
+      config = SimpleEnglish::Config.load
+      return [] if SimpleEnglish::Config.ignore?(config, path)
+      findings = SimpleEnglish.lint_file(path)
+      findings.nil? ? nil : SimpleEnglish::Config.filter(config, path, findings)
+    end
+
+    def respond(request, linter:)
+      return nil unless request.key?("id")
+      id = request.fetch("id")
+      method = request["method"]
+      return error(id, -32600, "Invalid Request") unless method.is_a?(String)
+      params = request["params"]
+      params = {} unless params.is_a?(Hash)
+      case method
+      when "initialize" then ok(id, initialize_result(params["protocolVersion"]))
+      when "tools/list" then ok(id, {"tools" => [lint_tool]})
+      when "tools/call" then tools_call(id, params, linter)
+      else error(id, -32601, "Method not found: #{method}")
+      end
+    end
+
+    def initialize_result(requested_version)
+      version = SUPPORTED_VERSIONS.include?(requested_version) ? requested_version : LATEST_VERSION
+      {
+        "protocolVersion" => version,
+        "capabilities" => {"tools" => {}},
+        "serverInfo" => {"name" => SERVER_NAME, "version" => SimpleEnglish::VERSION}
+      }
+    end
+
+    def lint_tool
+      {
+        "name" => "lint",
+        "description" =>
+          "Lint Markdown prose and code comments against plain-English rules " \
+          "(short sentences, active voice, no jargon, no filler). " \
+          "Input: a file path. Returns one line per finding, or 'clean' when " \
+          "nothing is flagged. Fix the findings, then call again until clean.",
+        "inputSchema" => {
+          "type" => "object",
+          "properties" => {"path" => {"type" => "string", "description" => "File to lint"}},
+          "required" => ["path"]
+        }
+      }
+    end
+
+    def tools_call(id, params, linter)
+      tool = params["name"]
+      return error(id, -32602, "Unknown tool: #{tool}") unless tool == "lint"
+      arguments = params["arguments"]
+      arguments = {} unless arguments.is_a?(Hash)
+      path = arguments["path"]
+      return ok(id, tool_error("the path argument is required.")) if path.nil? || path.to_s.empty?
+      return ok(id, tool_error("#{path} is a directory. Give one file.")) if File.directory?(path)
+      return ok(id, tool_error("file not found: #{path}")) unless File.exist?(path)
+      findings =
+        begin
+          linter.call(path)
+        rescue SimpleEnglish::Config::ConfigError => e
+          return ok(id, tool_error("invalid .simple-english.yml: #{e.message}"))
+        end
+      if findings.nil?
+        # A tool error, not a protocol error: clients show the text to the
+        # model, and this message is the one that tells it how to recover.
+        ok(id, tool_error("the se daemon did not answer. Run `se serve --detached` and retry."))
+      else
+        ok(id, {"content" => [{"type" => "text", "text" => render(path, findings)}], "isError" => false})
+      end
+    end
+
+    def render(path, findings)
+      return "clean" if findings.empty?
+      findings.map { |finding| finding.to_line(path) }.join("\n")
+    end
+
+    def tool_error(text)
+      {"content" => [{"type" => "text", "text" => text}], "isError" => true}
+    end
+
+    def ok(id, result)
+      {"jsonrpc" => "2.0", "id" => id, "result" => result}
+    end
+
+    def error(id, code, message)
+      {"jsonrpc" => "2.0", "id" => id, "error" => {"code" => code, "message" => message}}
+    end
+  end
+end

data/lib/simple_english/setup/config.rb

@@ -22,8 +22,19 @@ module SimpleEnglish
       raise ConfigError, ".simple-english.yml: #{e.message}"
     end
 
+    # Hooks pass absolute paths while ignore globs are written
+    # relative to the repo root (the CWD). Match both forms.
+    # realpath because CWD may be a symlink-resolved path while the
+    # caller's string still carries the symlink (TMPDIR on macOS).
     def ignore?(config, path)
-      config[:ignore].any? { |pattern| matches?(pattern, path) }
+      candidates = [path, relative_candidate(path)].compact
+      candidates.any? { |candidate| config[:ignore].any? { |pattern| matches?(pattern, candidate) } }
+    end
+
+    def relative_candidate(path)
+      pwd = Dir.pwd + "/"
+      resolved = File.exist?(path) ? File.realpath(path) : File.expand_path(path)
+      resolved.start_with?(pwd) ? resolved.delete_prefix(pwd) : nil
     end
 
     # File.fnmatch has no globstar: `**` never crosses directories.

data/lib/simple_english/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleEnglish
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/simple_english.rb

@@ -21,6 +21,7 @@ require_relative "simple_english/client/language_tool"
 require_relative "simple_english/client/daemon"
 require_relative "simple_english/daemon/engine"
 require_relative "simple_english/daemon/http"
+require_relative "simple_english/model_context_protocol"
 require_relative "simple_english/daemon/server"
 
 module SimpleEnglish
@@ -49,7 +50,7 @@ module SimpleEnglish
         return nil unless Client.ensure_up(install: Install.from_env)
         result = Client.lint(text, language: language)
         if result.nil?
-          warn "error: se daemon did not answer. Run `se serve` and read its output."
+          warn "error: se daemon did not answer. Run `#{Client.runner} serve` and read its output."
         end
         result
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_english
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - TonyCTHsu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tree_sitter_language_pack
@@ -153,6 +153,7 @@ files:
 - lib/simple_english/lint/segment.rb
 - lib/simple_english/lint/span.rb
 - lib/simple_english/lint/suppressions.rb
+- lib/simple_english/model_context_protocol.rb
 - lib/simple_english/setup/config.rb
 - lib/simple_english/setup/fingerprint.rb
 - lib/simple_english/setup/install.rb
@@ -165,7 +166,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/TonyCTHsu/simple-english
   source_code_uri: https://github.com/TonyCTHsu/simple-english
-  changelog_uri: https://github.com/TonyCTHsu/simple-english/blob/v0.4.1/CHANGELOG.md
+  changelog_uri: https://github.com/TonyCTHsu/simple-english/blob/v0.5.0/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: