simple_english 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6c725be18b4e942fa4e7fb13ca015901ceeae450aafe4c00eb27dfffabaf4ed
-  data.tar.gz: c9d1d0a62c474d3335fca783889a32610aa436f4e127d96a6aee336569d5ba41
+  metadata.gz: 8021741a0615e3d936a8a9bdabe7579fb1fa9641ce5061bf2d3a0e2bb24dd4d9
+  data.tar.gz: 87fb729f7e72ef9af5d3c63b305fdff9bea3b3aec034429ac52eaffb54639559
 SHA512:
-  metadata.gz: 97a9eea4051c526be80f2577cc2f835a7e89a1230891f222016ab1f02f490d7d8ed08212bf346ef8505a3a96d378d3f29a7548b03d33cd96211c236206b5cf49
-  data.tar.gz: f959023348c68024eef0e0533201c4f4802321ac71b90867f57c56e15f6d3c112589d0dc8892b5a43997c750b0084b15b6c8298df02a9dfba173e561daff49b4
+  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

@@ -76,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"
@@ -132,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
@@ -179,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/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.2"
+  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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_english
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - TonyCTHsu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-02 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.2/CHANGELOG.md
+  changelog_uri: https://github.com/TonyCTHsu/simple-english/blob/v0.5.0/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: