elelem-mcp 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 165e65bad3ab284e5049d9cffba0041be3f5c315253d48090d6dd7e754a4f715
4
- data.tar.gz: c96c690ff8008695fa8f1eb19a4aa4202d7543a622340d813b3d2a257d2adad3
3
+ metadata.gz: 3582800278834aca1ee1ae7f8efb9000a9d38de65960feea2dc199c5f3605c82
4
+ data.tar.gz: 923233a56b6b7279e2194e0f53ab8e0a3068c1e344ae83a5a34087f6e29e6f95
5
5
  SHA512:
6
- metadata.gz: 65822b02aa43aec269f68811654cd566baecf9629adb95e15c5ef934228f95c20a54d148cba59af8754ecc19e33a42e66543797dff149e9c5780d88a97065b35
7
- data.tar.gz: 7d2c03dac26fc843b9f8ea8734159de93509c81963528baee425810e440a51787db1d2f24cdb21574beb82e13d31114d8df2d5e2ca0cbcfafe885b0c648c60ba
6
+ metadata.gz: beb37281c0a440ae36ec41a8bc0ed94fbcc2fc292bbc925cf900616a65724ac1682734c01a3600a56cc8b501c2f99f0766952cf25dfbac1fb38139af29a24a1b
7
+ data.tar.gz: e894b3ac998adcab7d71fbde6b3749c353eb8c9fab7b5ce757942b0694cb70267448aeaa851eaf5516a49cf3d7f04a1fcbffba05469b9bc806165a1abb2d3450
@@ -0,0 +1,91 @@
1
+ As a `person who wants to give elelem tools from MCP servers`, I `want
2
+ a README and clear RubyGems links for elelem-mcp`, so that `I can
3
+ configure servers without reading the code and find the docs and
4
+ backlog from the gem page`.
5
+
6
+ # SYNOPSIS
7
+
8
+ Add a README, and point the gem's RubyGems links at elelem.sh and this
9
+ repository's backlog.
10
+
11
+ # DESCRIPTION
12
+
13
+ Two small changes that both shape what a newcomer sees first.
14
+
15
+ ## README
16
+
17
+ The repository has no README. It should cover:
18
+
19
+ * Install, and the loader file elelem needs to load a gem plugin
20
+ (`~/.agents/plugins/mcp.rb` containing `require "elelem/mcp"`),
21
+ until core loads installed plugins on its own.
22
+ * Configuration: `~/.agents/mcp.json` and `.agents/mcp.json`, with an
23
+ example for a stdio server and an HTTP server.
24
+ * OAuth for HTTP servers: the browser step, where tokens are stored,
25
+ and how to remove them.
26
+ * How tools appear: one loader thread per server, a server that fails
27
+ is reported on stderr and skipped, and `elelem ask` waits up to 30
28
+ seconds for servers to load.
29
+ * A link to https://elelem.sh/plugins/mcp/ for the full guide.
30
+
31
+ The elelem.sh plugin page can be the source for the text. Show commands
32
+ without a leading `$`, so they can be pasted.
33
+
34
+ ## Gem metadata
35
+
36
+ RubyGems shows `homepage_uri` and the other `metadata` links on every
37
+ gem page. Today `elelem-mcp.gemspec` sets `spec.homepage`
38
+ to the site root (https://elelem.sh) and sets only `homepage_uri`,
39
+ `source_code_uri`, `allowed_push_host` and
40
+ `rubygems_mfa_required`.
41
+ There is no documentation, bug tracker or changelog link.
42
+
43
+ Proposed change:
44
+
45
+ ```ruby
46
+ spec.homepage = "https://elelem.sh/plugins/mcp/"
47
+ spec.metadata["homepage_uri"] = spec.homepage
48
+ spec.metadata["source_code_uri"] = "https://github.com/elelem-sh/mcp"
49
+ spec.metadata["documentation_uri"] = spec.homepage
50
+ spec.metadata["bug_tracker_uri"] = "https://github.com/elelem-sh/mcp/tree/main/.agents/backlog"
51
+ spec.metadata["changelog_uri"] = "https://github.com/elelem-sh/mcp/blob/main/CHANGELOG.md"
52
+ ```
53
+
54
+ The original proposal pointed `bug_tracker_uri` at GitHub Issues on
55
+ elelem-sh/elelem.sh, filtered by label. That no longer fits: the
56
+ project is moving its backlog out of GitHub Issues and into
57
+ `.agents/backlog` story files in each repository, so the bug tracker
58
+ link points at this repository's backlog directory instead.
59
+
60
+ /man/mcp/ redirects to /plugins/mcp/ on elelem.sh, so a
61
+ separate documentation_uri adds nothing. Point both at the plugin page.
62
+ CHANGELOG.md exists on main, so the changelog link works today.
63
+
64
+ Keep `allowed_push_host` and `rubygems_mfa_required` as they are.
65
+ RubyGems only shows the new links after the next release.
66
+
67
+ # SEE ALSO
68
+
69
+ * [ ] lib/elelem/mcp.rb:37-60 - setup and loader threads
70
+ * [ ] lib/elelem/mcp/client.rb:7-10 - config paths
71
+ * [ ] lib/elelem/mcp/oauth.rb, lib/elelem/mcp/token_storage.rb
72
+ * [ ] elelem-mcp.gemspec:13 - spec.homepage and metadata
73
+ * [ ] https://elelem.sh/plugins/mcp/ - source for README text
74
+ * [ ] Formerly elelem-sh/elelem.sh#23
75
+ * [ ] Formerly elelem-sh/elelem.sh#41
76
+
77
+ # Tasks
78
+
79
+ * [ ] TBD (filled in design mode)
80
+
81
+ # Acceptance Criteria
82
+
83
+ * [ ] README.md exists and covers the points above
84
+ * [ ] Defaults in the README match the code
85
+ * [ ] Commands in the README have no leading `$`
86
+ * [ ] `spec.homepage` and `homepage_uri` are https://elelem.sh/plugins/mcp/
87
+ * [ ] `bug_tracker_uri` points at this repository's `.agents/backlog`,
88
+ not at GitHub Issues
89
+ * [ ] `changelog_uri` and `source_code_uri` point at this repository
90
+ * [ ] `gem build` succeeds and `gem spec` on the built gem shows every
91
+ link
@@ -0,0 +1,63 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ permissions: {}
9
+
10
+ concurrency:
11
+ group: release
12
+ cancel-in-progress: false
13
+
14
+ jobs:
15
+ test:
16
+ runs-on: ubuntu-latest
17
+ permissions:
18
+ contents: read
19
+ steps:
20
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
21
+ with:
22
+ persist-credentials: false
23
+ - uses: ruby/setup-ruby@3ff19f5e2baf30647122352b96108b1fbe250c64 # v1.299.0
24
+ with:
25
+ ruby-version: "4.0"
26
+ bundler-cache: true
27
+ - run: bin/test
28
+ - run: bin/lint
29
+
30
+ release-please:
31
+ needs: test
32
+ runs-on: ubuntu-latest
33
+ permissions:
34
+ contents: write
35
+ issues: write
36
+ pull-requests: write
37
+ outputs:
38
+ release_created: ${{ steps.release.outputs.release_created }}
39
+ steps:
40
+ - id: release
41
+ uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
42
+ with:
43
+ config-file: release-please-config.json
44
+ manifest-file: .release-please-manifest.json
45
+
46
+ publish:
47
+ needs: release-please
48
+ if: needs.release-please.outputs.release_created == 'true'
49
+ runs-on: ubuntu-latest
50
+ permissions:
51
+ contents: write
52
+ id-token: write
53
+ steps:
54
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
55
+ with:
56
+ persist-credentials: false
57
+ - uses: ruby/setup-ruby@3ff19f5e2baf30647122352b96108b1fbe250c64 # v1.299.0
58
+ with:
59
+ ruby-version: "4.0"
60
+ bundler-cache: true
61
+ - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1
62
+ with:
63
+ await-release: false
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.2.2"
3
+ }
data/.rubocop.yml ADDED
@@ -0,0 +1,66 @@
1
+ AllCops:
2
+ NewCops: enable
3
+ TargetRubyVersion: 4.0
4
+ SuggestExtensions: false
5
+ Exclude:
6
+ - "pkg/**/*"
7
+ - "bin/**/*"
8
+ - "vendor/**/*"
9
+ - "fixtures/**/*"
10
+
11
+ Metrics:
12
+ Enabled: false
13
+
14
+ # exe/elelem runs with -W0, which silences Kernel#warn.
15
+ Style/StderrPuts:
16
+ Enabled: false
17
+
18
+ Naming/PredicateMethod:
19
+ AllowedMethods:
20
+ - call
21
+ - run
22
+ - summarize
23
+ - prompt
24
+
25
+ Naming/MethodParameterName:
26
+ AllowedNames:
27
+ - me
28
+ - id
29
+ - as
30
+ - io
31
+
32
+ Style/GlobalVars:
33
+ Exclude:
34
+ - "spec/**/*"
35
+
36
+ Lint/EmptyBlock:
37
+ Exclude:
38
+ - "spec/**/*"
39
+
40
+ Lint/UselessDefaultValueArgument:
41
+ Enabled: false
42
+
43
+ Lint/RedundantRequireStatement:
44
+ Enabled: false
45
+
46
+ Lint/UnusedBlockArgument:
47
+ IgnoreEmptyBlocks: true
48
+ AllowUnusedKeywordArguments: true
49
+
50
+ Style/Documentation:
51
+ Enabled: false
52
+
53
+ Style/FormatStringToken:
54
+ Enabled: false
55
+
56
+ Style/FrozenStringLiteralComment:
57
+ Enabled: true
58
+
59
+ Style/StringLiterals:
60
+ EnforcedStyle: double_quotes
61
+
62
+ Style/StringLiteralsInInterpolation:
63
+ EnforcedStyle: double_quotes
64
+
65
+ Layout/LineLength:
66
+ Max: 120
data/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ ## [0.2.2](https://github.com/elelem-sh/mcp/compare/v0.2.1...v0.2.2) (2026-11-17)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * require elelem >= 0.13.1, the release the specs are written against ([08ee8ac](https://github.com/elelem-sh/mcp/commit/08ee8ace24fc152783a2e26eca1339c8b634130a))
9
+
10
+ ## [0.2.1](https://github.com/elelem-sh/mcp/compare/v0.2.0...v0.2.1) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * drain MCP server stderr, wait for servers in elelem ask, and accept type stdio (elelem-sh/elelem.sh[#45](https://github.com/elelem-sh/mcp/issues/45)) ([e8d2ed6](https://github.com/elelem-sh/mcp/commit/e8d2ed6ee292cf2c1274bc866f682317a6248ca8))
16
+ * drop the digest dependency, which ships with ruby and clashes with the publish job ([e8fd648](https://github.com/elelem-sh/mcp/commit/e8fd648ca0658399a93887d02d413fd68bea7255))
17
+ * load each MCP server on its own and print the ones that fail ([67b0939](https://github.com/elelem-sh/mcp/commit/67b0939646d6ddd3eb7c1846169de2fa334a605c))
18
+ * MCP asks for protocol 2025-11-25, keeps the server's answer, and sends it over HTTP (elelem-sh/elelem.sh[#33](https://github.com/elelem-sh/mcp/issues/33)) ([dbd9f96](https://github.com/elelem-sh/mcp/commit/dbd9f96b711c764ed329bfe09af82e2e45209f3e))
19
+ * name the unsupported MCP server type in the error ([cd5f8fc](https://github.com/elelem-sh/mcp/commit/cd5f8fc08f33252dbb6fa2f49723461fadb47629))
20
+ * OAuth discovery keeps the server's port (elelem-sh/elelem.sh[#33](https://github.com/elelem-sh/mcp/issues/33)) ([6f81560](https://github.com/elelem-sh/mcp/commit/6f81560c76f8a434e62e5589e59d4cc00a916cf1))
21
+ * relock elelem to 0.11.0, a real published version ([b0f0e6b](https://github.com/elelem-sh/mcp/commit/b0f0e6b68423df31a406434b236dd6eef5e15bd9))
22
+ * require elelem ~> 0.12, the floor builtins/skills actually need ([c26b32d](https://github.com/elelem-sh/mcp/commit/c26b32dcaba7d7952a02f2b79f29cb1d4fbd0d32))
23
+ * the OAuth callback listens on 127.0.0.1, and tool payloads log at debug (elelem-sh/elelem.sh[#5](https://github.com/elelem-sh/mcp/issues/5)) ([1d19539](https://github.com/elelem-sh/mcp/commit/1d19539e4b342c41e813923470265f6fc29b4d54))
@@ -18,20 +18,22 @@ module Elelem
18
18
  @servers = {}
19
19
  end
20
20
 
21
- def tools
22
- @config.fetch("mcpServers", {}).flat_map do |name, _|
23
- server(name).tools.map do |tool|
24
- [
25
- "#{name}_#{tool["name"]}",
26
- {
27
- description: tool["description"],
28
- params: symbolize(tool.dig("inputSchema", "properties") || {}),
29
- required: tool.dig("inputSchema", "required") || [],
30
- fn: ->(a) { server(name).call(tool["name"], a) }
31
- }
32
- ]
33
- end
34
- end.to_h
21
+ def server_names
22
+ @config.fetch("mcpServers", {}).keys
23
+ end
24
+
25
+ def tools_for(name)
26
+ server(name).tools.to_h do |tool|
27
+ [
28
+ "#{name}_#{tool["name"]}",
29
+ {
30
+ description: tool["description"],
31
+ params: symbolize(tool.dig("inputSchema", "properties") || {}),
32
+ required: tool.dig("inputSchema", "required") || [],
33
+ fn: ->(a) { server(name).call(tool["name"], a) }
34
+ }
35
+ ]
36
+ end
35
37
  end
36
38
 
37
39
  def close
@@ -49,7 +51,7 @@ module Elelem
49
51
  file = File.expand_path(path)
50
52
  next unless File.exist?(file)
51
53
 
52
- config = JSON.parse(IO.read(file))
54
+ config = JSON.parse(File.read(file))
53
55
  servers = config.fetch("mcpServers", {})
54
56
  merged["mcpServers"] = (merged["mcpServers"] || {}).merge(servers)
55
57
  end
@@ -60,22 +62,28 @@ module Elelem
60
62
  end
61
63
 
62
64
  def build_server(config)
63
- if config["type"] == "http"
64
- HttpServer.new(url: config["url"], headers: config["headers"] || {})
65
- else
66
- Server.new(**config.transform_keys(&:to_sym))
65
+ config = config.dup
66
+ type = config.delete("type") || (config.key?("url") ? "http" : "stdio")
67
+ case type
68
+ when "http" then HttpServer.new(url: config["url"], headers: config["headers"] || {})
69
+ when "stdio" then Server.new(**config.transform_keys(&:to_sym))
70
+ else raise "unsupported type: #{type}"
67
71
  end
68
72
  end
69
73
  end
70
74
 
75
+ PROTOCOL_VERSION = "2025-11-25"
76
+
71
77
  module ServerInterface
78
+ attr_reader :protocol_version
79
+
72
80
  def tools
73
81
  request("tools/list")["tools"]
74
82
  end
75
83
 
76
84
  def call(name, args)
77
85
  result = request("tools/call", { name: name, arguments: args })
78
- Elelem.logger.info({ tool: name, args: args, result: result }.to_json)
86
+ Elelem.logger.debug({ tool: name, args: args, result: result }.to_json)
79
87
  content = extract_content(result)
80
88
  result["isError"] ? { error: content } : { content: content }
81
89
  end
@@ -90,12 +98,15 @@ module Elelem
90
98
 
91
99
  private
92
100
 
101
+ # Asks for the version this client follows, then speaks whichever the
102
+ # server answers with.
93
103
  def handshake!
94
- request("initialize", {
95
- protocolVersion: "2025-06-18",
96
- capabilities: {},
97
- clientInfo: { name: "elelem", version: Elelem::MCP::VERSION }
98
- })
104
+ result = request("initialize", {
105
+ protocolVersion: PROTOCOL_VERSION,
106
+ capabilities: {},
107
+ clientInfo: { name: "elelem", version: Elelem::MCP::VERSION }
108
+ })
109
+ @protocol_version = result&.dig("protocolVersion") || PROTOCOL_VERSION
99
110
  notify("notifications/initialized")
100
111
  end
101
112
  end
@@ -105,9 +116,12 @@ module Elelem
105
116
 
106
117
  def initialize(command:, args: [], env: {})
107
118
  resolved_env = env.transform_values do |v|
108
- v.gsub(/\$\{(\w+)\}/) { ENV[$1] || raise("Missing environment variable: #{$1}") }
119
+ v.gsub(/\$\{(\w+)\}/) do
120
+ ENV[::Regexp.last_match(1)] || raise("Missing environment variable: #{::Regexp.last_match(1)}")
121
+ end
109
122
  end
110
123
  @stdin, @stdout, @stderr, @wait = Open3.popen3(resolved_env, command, *args)
124
+ @drain = drain(@stderr)
111
125
  @id = 0
112
126
  handshake!
113
127
  end
@@ -119,12 +133,22 @@ module Elelem
119
133
  nil
120
134
  end
121
135
  @wait.kill
136
+ @drain.join(1)
122
137
  rescue StandardError
123
138
  nil
124
139
  end
125
140
 
126
141
  private
127
142
 
143
+ # A server that writes to stderr would block once the pipe fills, so read it.
144
+ def drain(io)
145
+ Thread.new do
146
+ io.each_line { |line| Elelem.logger.debug("mcp stderr: #{line.chomp}") }
147
+ rescue IOError
148
+ nil
149
+ end
150
+ end
151
+
128
152
  def request(method, params = {})
129
153
  send_msg(id: @id += 1, method: method, params: params)
130
154
  read_response(@id)
@@ -172,7 +196,7 @@ module Elelem
172
196
  def resolve_headers(headers)
173
197
  headers.transform_values do |v|
174
198
  v.gsub(/\$\{(\w+)\}/) do
175
- ENV[$1] || raise("Missing environment variable: #{$1}")
199
+ ENV[::Regexp.last_match(1)] || raise("Missing environment variable: #{::Regexp.last_match(1)}")
176
200
  end
177
201
  end
178
202
  end
@@ -223,6 +247,8 @@ module Elelem
223
247
  def request_headers
224
248
  base = { "Accept" => "application/json, text/event-stream" }
225
249
  base["Mcp-Session-Id"] = @session_id if @session_id
250
+ # Streamable HTTP needs the negotiated version on every request after initialize.
251
+ base["MCP-Protocol-Version"] = @protocol_version if @protocol_version
226
252
  base["Authorization"] = "Bearer #{@access_token}" if @access_token
227
253
  @headers.merge(base)
228
254
  end
@@ -3,8 +3,8 @@
3
3
  module Elelem
4
4
  module MCP
5
5
  class OAuth
6
- CALLBACK_PORT = 18273
7
- REDIRECT_URI = "http://127.0.0.1:#{CALLBACK_PORT}/callback"
6
+ CALLBACK_PORT = 18_273
7
+ REDIRECT_URI = "http://127.0.0.1:#{CALLBACK_PORT}/callback".freeze
8
8
 
9
9
  def initialize(resource_url, http: HttpAdapter.new)
10
10
  @resource_url = resource_url
@@ -73,13 +73,12 @@ module Elelem
73
73
 
74
74
  tokens["access_token"]
75
75
  rescue StandardError => e
76
- warn "Token refresh failed: #{e.message}"
76
+ $stderr.puts "elelem-mcp: token refresh failed: #{e.message}"
77
77
  authorize
78
78
  end
79
79
 
80
80
  def discover_auth_server
81
- resource_uri = URI.parse(@resource_url)
82
- metadata_url = "#{resource_uri.scheme}://#{resource_uri.host}/.well-known/oauth-protected-resource"
81
+ metadata_url = URI.join(@resource_url, "/.well-known/oauth-protected-resource").to_s
83
82
 
84
83
  resource_metadata = fetch_json(metadata_url)
85
84
  auth_server_url = resource_metadata["authorization_servers"]&.first
@@ -138,17 +137,16 @@ module Elelem
138
137
  end
139
138
 
140
139
  def open_browser(url)
141
- commands = ["xdg-open", "open", "start"]
142
- commands.each do |cmd|
143
- return if system(cmd, url, out: File::NULL, err: File::NULL)
144
- end
145
- warn "Open this URL in your browser: #{url}"
140
+ commands = %w[xdg-open open start]
141
+ opened = commands.any? { |cmd| system(cmd, url, out: File::NULL, err: File::NULL) }
142
+ $stderr.puts "Open this URL in your browser: #{url}" unless opened
146
143
  end
147
144
 
148
145
  def wait_for_callback(expected_state)
149
146
  code = nil
150
147
  @server = WEBrick::HTTPServer.new(
151
148
  Port: CALLBACK_PORT,
149
+ BindAddress: "127.0.0.1",
152
150
  Logger: WEBrick::Log.new(File::NULL),
153
151
  AccessLog: []
154
152
  )
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Elelem
4
4
  module MCP
5
- VERSION = "0.2.0"
5
+ VERSION = "0.2.2"
6
6
  end
7
7
  end
data/lib/elelem/mcp.rb CHANGED
@@ -17,24 +17,45 @@ require_relative "mcp/token_storage"
17
17
  require_relative "mcp/oauth"
18
18
  require_relative "mcp/client"
19
19
 
20
+ module Elelem
21
+ module MCP
22
+ # Waits for every loader, but no more than timeout seconds in all.
23
+ def self.wait(threads, timeout: 30)
24
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
25
+ threads.each { |t| t.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max) }
26
+ end
27
+
28
+ # A person at a terminal can start typing while servers load. A one-shot
29
+ # run, such as elelem ask, has to wait or its first turn has no MCP tools.
30
+ def self.interactive?(session)
31
+ !session.respond_to?(:input) || session.input.interactive?
32
+ end
33
+ end
34
+ end
35
+
20
36
  Elelem.configure do |config|
21
- config.setup(:mcp) do |agent|
37
+ config.setup(:mcp) do |session|
22
38
  mcp = Elelem::MCP::Client.memoized
23
39
 
24
- Thread.new do
25
- mcp.tools.each do |name, tool|
26
- next if agent.toolbox.tools.key?(name)
40
+ # One thread per server, so a broken or slow server does not hold back the others.
41
+ threads = mcp.server_names.map do |server|
42
+ Thread.new do
43
+ mcp.tools_for(server).each do |name, tool|
44
+ next if session.toolbox.tools.key?(name)
27
45
 
28
- agent.toolbox.add(
29
- name,
30
- description: tool[:description],
31
- params: tool[:params],
32
- required: tool[:required],
33
- &tool[:fn]
34
- )
46
+ session.toolbox.add(
47
+ name,
48
+ description: tool[:description],
49
+ params: tool[:params],
50
+ required: tool[:required],
51
+ &tool[:fn]
52
+ )
53
+ end
54
+ rescue StandardError => e
55
+ $stderr.puts "elelem-mcp: #{server}: #{e.message}"
35
56
  end
36
- rescue => e
37
- warn "MCP failed: #{e.message}"
38
57
  end
58
+ Elelem::MCP.wait(threads) unless Elelem::MCP.interactive?(session)
59
+ threads
39
60
  end
40
61
  end
@@ -0,0 +1,12 @@
1
+ {
2
+ "bootstrap-sha": "f51f7a671b8a01de32b68b83f9b6a92a0f91b206",
3
+ "packages": {
4
+ ".": {
5
+ "release-type": "ruby",
6
+ "package-name": "elelem-mcp",
7
+ "version-file": "lib/elelem/mcp/version.rb",
8
+ "bump-minor-pre-major": true,
9
+ "include-component-in-tag": false
10
+ }
11
+ }
12
+ }
@@ -0,0 +1,61 @@
1
+ # frozen_string_literal: true
2
+
3
+ RSpec.describe Elelem::MCP::Client do
4
+ subject(:client) { described_class.new([config]) }
5
+
6
+ let(:dir) { Dir.mktmpdir }
7
+ let(:config) { File.join(dir, "mcp.json") }
8
+ let(:echo) { { "command" => RbConfig.ruby, "args" => [File.expand_path("../../fixtures/echo_server.rb", __dir__)] } }
9
+
10
+ before do
11
+ servers = { "echo" => echo, "broken" => { "command" => "/nonexistent/mcp" } }
12
+ File.write(config, JSON.generate("mcpServers" => servers))
13
+ end
14
+
15
+ after do
16
+ client.close
17
+ FileUtils.rm_rf(dir)
18
+ end
19
+
20
+ it "lists every configured server" do
21
+ expect(client.server_names).to eq(%w[echo broken])
22
+ end
23
+
24
+ it "loads one server's tools when another fails" do
25
+ expect { client.tools_for("broken") }.to raise_error(SystemCallError)
26
+ expect(client.tools_for("echo").keys).to eq(["echo_say"])
27
+ end
28
+
29
+ it "answers when the server writes a lot to stderr" do
30
+ noisy = { "command" => RbConfig.ruby, "args" => [File.expand_path("../../fixtures/noisy_server.rb", __dir__)] }
31
+ File.write(config, JSON.generate("mcpServers" => { "noisy" => noisy }))
32
+
33
+ Timeout.timeout(10) { expect(client.tools_for("noisy").keys).to eq(["noisy_say"]) }
34
+ end
35
+
36
+ it "accepts type stdio, and takes a url without a type as http" do
37
+ servers = { "s" => echo.merge("type" => "stdio"), "h" => { "url" => "http://127.0.0.1:1/mcp" } }
38
+ File.write(config, JSON.generate("mcpServers" => servers))
39
+
40
+ expect(client.tools_for("s").keys).to eq(["s_say"])
41
+ expect { client.tools_for("h") }.to raise_error(SystemCallError)
42
+ end
43
+
44
+ it "names an unsupported type" do
45
+ File.write(config, JSON.generate("mcpServers" => { "x" => { "type" => "sse", "url" => "http://h/" } }))
46
+
47
+ expect { client.tools_for("x") }.to raise_error("unsupported type: sse")
48
+ end
49
+
50
+ it "asks for 2025-11-25 and keeps the version the server answers with" do
51
+ client.tools_for("echo")
52
+ server = client.send(:server, "echo")
53
+
54
+ expect(Elelem::MCP::PROTOCOL_VERSION).to eq("2025-11-25")
55
+ expect(server.protocol_version).to eq("2025-06-18")
56
+ end
57
+
58
+ it "calls a loaded tool" do
59
+ expect(client.tools_for("echo")["echo_say"][:fn].call("text" => "hi")).to eq(content: "hi")
60
+ end
61
+ end
@@ -81,6 +81,13 @@ RSpec.describe Elelem::MCP::HttpServer do
81
81
  expect(headers["Accept"]).to eq("application/json, text/event-stream")
82
82
  end
83
83
 
84
+ it "includes the negotiated protocol version once there is one" do
85
+ expect(subject.send(:request_headers)).not_to have_key("MCP-Protocol-Version")
86
+
87
+ subject.instance_variable_set(:@protocol_version, "2025-11-25")
88
+ expect(subject.send(:request_headers)["MCP-Protocol-Version"]).to eq("2025-11-25")
89
+ end
90
+
84
91
  it "includes session ID when set" do
85
92
  subject.instance_variable_set(:@session_id, "abc123")
86
93
  headers = subject.send(:request_headers)
@@ -15,9 +15,9 @@ RSpec.describe Elelem::MCP::OAuth do
15
15
  context "with valid cached token" do
16
16
  it "returns cached access_token" do
17
17
  allow(storage).to receive(:load).with(resource_url).and_return({
18
- access_token: "cached_token",
19
- expires_at: Time.now.to_i + 3600
20
- })
18
+ access_token: "cached_token",
19
+ expires_at: Time.now.to_i + 3600
20
+ })
21
21
 
22
22
  expect(subject.token).to eq("cached_token")
23
23
  end
@@ -34,14 +34,14 @@ RSpec.describe Elelem::MCP::OAuth do
34
34
 
35
35
  it "refreshes using refresh_token" do
36
36
  allow(storage).to receive(:load).with(resource_url).and_return({
37
- access_token: "old_token",
38
- refresh_token: "refresh_abc",
39
- expires_at: Time.now.to_i - 100
40
- })
37
+ access_token: "old_token",
38
+ refresh_token: "refresh_abc",
39
+ expires_at: Time.now.to_i - 100
40
+ })
41
41
 
42
42
  allow(storage).to receive(:load_client).with(resource_url).and_return({
43
- client_id: "elelem-123"
44
- })
43
+ client_id: "elelem-123"
44
+ })
45
45
 
46
46
  resource_response = double(body: { "authorization_servers" => ["https://auth.example.com"] }.to_json)
47
47
  auth_response = double(body: auth_metadata.to_json)
@@ -90,3 +90,33 @@ RSpec.describe Elelem::MCP::OAuth do
90
90
  end
91
91
  end
92
92
  end
93
+
94
+ RSpec.describe Elelem::MCP::OAuth, "callback" do
95
+ it "listens on 127.0.0.1 only" do
96
+ server = instance_double(WEBrick::HTTPServer, mount_proc: nil, shutdown: nil)
97
+ allow(server).to receive(:start) { raise Timeout::Error }
98
+ allow(WEBrick::HTTPServer).to receive(:new).and_return(server)
99
+
100
+ oauth = described_class.new("https://mcp.example.com/mcp", http: double("http"))
101
+ expect { oauth.send(:wait_for_callback, "state") }.to raise_error("OAuth callback timed out")
102
+ expect(WEBrick::HTTPServer).to have_received(:new).with(hash_including(BindAddress: "127.0.0.1"))
103
+ ensure
104
+ oauth&.instance_variable_set(:@server, nil) # its at_exit shutdown must not reach the double
105
+ end
106
+ end
107
+
108
+ RSpec.describe Elelem::MCP::OAuth, "discovery" do
109
+ it "keeps the port of the server's URL" do
110
+ http = double("http")
111
+ asked = []
112
+ allow(http).to receive(:get) do |url, &block|
113
+ asked << url
114
+ body = url.include?("protected-resource") ? { authorization_servers: ["http://auth:9000"] } : {}
115
+ block.call(double(body: JSON.generate(body)))
116
+ end
117
+
118
+ described_class.new("http://localhost:8080/mcp", http: http).send(:discover_auth_server)
119
+
120
+ expect(asked.first).to eq("http://localhost:8080/.well-known/oauth-protected-resource")
121
+ end
122
+ end
@@ -7,7 +7,11 @@ RSpec.describe Elelem::MCP::TokenStorage do
7
7
  let(:token_dir) { File.expand_path("~/.config/elelem/tokens") }
8
8
 
9
9
  after do
10
- Dir.glob(File.join(token_dir, "*.json")).each { |f| File.delete(f) rescue nil }
10
+ Dir.glob(File.join(token_dir, "*.json")).each do |f|
11
+ File.delete(f)
12
+ rescue StandardError
13
+ nil
14
+ end
11
15
  end
12
16
 
13
17
  describe "#save and #load" do
@@ -0,0 +1,39 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "open3"
4
+
5
+ RSpec.describe "the mcp setup" do
6
+ let(:lib) { File.expand_path("../../lib", __dir__) }
7
+ let(:echo) { File.expand_path("../fixtures/echo_server.rb", __dir__) }
8
+ let(:script) do
9
+ 'require "elelem/mcp"; ' \
10
+ "puts Elelem.build(input: Elelem::NullInput.new, output: Elelem::NullOutput.new).toolbox.tools.keys"
11
+ end
12
+
13
+ def build_session_in(dir)
14
+ servers = {
15
+ "broken" => { "command" => "/nonexistent/mcp" },
16
+ "echo" => { "command" => RbConfig.ruby, "args" => [echo] }
17
+ }
18
+ FileUtils.mkdir_p(File.join(dir, ".agents"))
19
+ File.write(File.join(dir, ".agents/mcp.json"), JSON.generate("mcpServers" => servers))
20
+ Open3.capture3({ "HOME" => dir }, RbConfig.ruby, "-I", lib, "-e", script, chdir: dir)
21
+ end
22
+
23
+ it "waits for the servers when the input is not interactive, and loads the tools of the working one" do
24
+ Dir.mktmpdir do |dir|
25
+ tools, _, status = build_session_in(dir)
26
+
27
+ expect(status).to be_success
28
+ expect(tools.lines(chomp: true)).to include("echo_say")
29
+ end
30
+ end
31
+
32
+ it "names the server that failed" do
33
+ Dir.mktmpdir do |dir|
34
+ _, errors, = build_session_in(dir)
35
+
36
+ expect(errors).to eq("elelem-mcp: broken: No such file or directory - /nonexistent/mcp\n")
37
+ end
38
+ end
39
+ end
@@ -0,0 +1,24 @@
1
+ # frozen_string_literal: true
2
+
3
+ # A stdio MCP server with one tool, "say", that returns its text.
4
+ require "json"
5
+
6
+ SAY = {
7
+ name: "say",
8
+ description: "Echo text",
9
+ inputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] }
10
+ }.freeze
11
+
12
+ RESULTS = {
13
+ "initialize" => ->(_) { { protocolVersion: "2025-06-18", capabilities: {}, serverInfo: { name: "echo" } } },
14
+ "tools/list" => ->(_) { { tools: [SAY] } },
15
+ "tools/call" => ->(m) { { content: [{ type: "text", text: m.dig("params", "arguments", "text") }] } }
16
+ }.freeze
17
+
18
+ $stdout.sync = true
19
+ $stdin.each_line do |line|
20
+ message = JSON.parse(line)
21
+ next unless message["id"]
22
+
23
+ puts({ jsonrpc: "2.0", id: message["id"], result: RESULTS.fetch(message["method"]).call(message) }.to_json)
24
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ # The echo server, after writing more to stderr than a pipe holds.
4
+ $stderr.write("x" * 1_000_000)
5
+ load File.expand_path("echo_server.rb", __dir__)
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: elelem-mcp
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.2.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - mo khan
@@ -23,34 +23,26 @@ dependencies:
23
23
  - - "~>"
24
24
  - !ruby/object:Gem::Version
25
25
  version: '0.3'
26
- - !ruby/object:Gem::Dependency
27
- name: digest
28
- requirement: !ruby/object:Gem::Requirement
29
- requirements:
30
- - - "~>"
31
- - !ruby/object:Gem::Version
32
- version: '3.2'
33
- type: :runtime
34
- prerelease: false
35
- version_requirements: !ruby/object:Gem::Requirement
36
- requirements:
37
- - - "~>"
38
- - !ruby/object:Gem::Version
39
- version: '3.2'
40
26
  - !ruby/object:Gem::Dependency
41
27
  name: elelem
42
28
  requirement: !ruby/object:Gem::Requirement
43
29
  requirements:
44
- - - "~>"
30
+ - - ">="
45
31
  - !ruby/object:Gem::Version
46
- version: '0.1'
32
+ version: 0.13.1
33
+ - - "<"
34
+ - !ruby/object:Gem::Version
35
+ version: '1'
47
36
  type: :runtime
48
37
  prerelease: false
49
38
  version_requirements: !ruby/object:Gem::Requirement
50
39
  requirements:
51
- - - "~>"
40
+ - - ">="
41
+ - !ruby/object:Gem::Version
42
+ version: 0.13.1
43
+ - - "<"
52
44
  - !ruby/object:Gem::Version
53
- version: '0.1'
45
+ version: '1'
54
46
  - !ruby/object:Gem::Dependency
55
47
  name: fileutils
56
48
  requirement: !ruby/object:Gem::Requirement
@@ -171,7 +163,12 @@ executables: []
171
163
  extensions: []
172
164
  extra_rdoc_files: []
173
165
  files:
166
+ - ".agents/backlog/001-readme-and-gem-metadata.md"
167
+ - ".github/workflows/release.yml"
168
+ - ".release-please-manifest.json"
174
169
  - ".rspec"
170
+ - ".rubocop.yml"
171
+ - CHANGELOG.md
175
172
  - LICENSE.txt
176
173
  - Rakefile
177
174
  - lib/elelem/mcp.rb
@@ -179,17 +176,23 @@ files:
179
176
  - lib/elelem/mcp/oauth.rb
180
177
  - lib/elelem/mcp/token_storage.rb
181
178
  - lib/elelem/mcp/version.rb
179
+ - release-please-config.json
180
+ - spec/elelem/mcp/client_spec.rb
182
181
  - spec/elelem/mcp/http_server_spec.rb
183
182
  - spec/elelem/mcp/oauth_spec.rb
184
183
  - spec/elelem/mcp/token_storage_spec.rb
184
+ - spec/elelem/mcp_spec.rb
185
+ - spec/fixtures/echo_server.rb
186
+ - spec/fixtures/noisy_server.rb
185
187
  - spec/spec_helper.rb
186
- homepage: https://src.mokhan.ca/elelem/mcp
188
+ homepage: https://elelem.sh
187
189
  licenses:
188
190
  - MIT
189
191
  metadata:
190
192
  allowed_push_host: https://rubygems.org
191
- homepage_uri: https://src.mokhan.ca/elelem/mcp
192
- source_code_uri: https://src.mokhan.ca/elelem/mcp
193
+ homepage_uri: https://elelem.sh
194
+ source_code_uri: https://github.com/elelem-sh/mcp
195
+ rubygems_mfa_required: 'true'
193
196
  rdoc_options: []
194
197
  require_paths:
195
198
  - lib
@@ -204,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
204
207
  - !ruby/object:Gem::Version
205
208
  version: '0'
206
209
  requirements: []
207
- rubygems_version: 4.0.20
210
+ rubygems_version: 4.0.6
208
211
  specification_version: 4
209
212
  summary: MCP (Model Context Protocol) client support for elelem.
210
213
  test_files: []