mcp-datacircle 0.1.0
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 +7 -0
- data/LICENSE.txt +21 -0
- data/README.md +85 -0
- data/exe/mcp-datacircle +7 -0
- data/lib/mcp/datacircle/calls.rb +146 -0
- data/lib/mcp/datacircle/client.rb +76 -0
- data/lib/mcp/datacircle/tools.rb +120 -0
- data/lib/mcp/datacircle/version.rb +7 -0
- data/lib/mcp/datacircle.rb +44 -0
- metadata +76 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 5df87a8979e3bde2c52d42cf2f2e60f26f8fb476c61487f3bb2eb2cf14aa394e
|
|
4
|
+
data.tar.gz: b433f02b63464676adda52e1cd101b93c32fcdcdc29a11637e323496dbdc42fc
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: b2f6197be69ece07616fdcb0fd4bbb241aecd1ae4bd9dda6d992ff1962a825c7efa245a4cea31e47f5dd973fac40e44b6d3d921d673edb92fd74f302dce12174
|
|
7
|
+
data.tar.gz: da9d913875f6a386f164622d18fc6ccf220277e274a646e7cddb852a77b88c9b522d8c69385034f83bba86a3fd0b088b26c7aace14c25a5dc2fa31d0e3a00bec
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Datacircle
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Datacircle tools for the MCP Ruby SDK
|
|
2
|
+
|
|
3
|
+
Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website.
|
|
4
|
+
|
|
5
|
+
Our website: https://datacircle.dev
|
|
6
|
+
|
|
7
|
+
This gem adds four tools to a server that uses the [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) (the `mcp` gem). The tools call Datacircle's open API, https://api.datacircle.dev/v1. You need no key and no account.
|
|
8
|
+
|
|
9
|
+
| Tool | What the tool gives | Call |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `datacircle_list_apis` | Every GTM API on Datacircle, with the API's slug, number of plans, number of providers and best plan | `GET /apis` |
|
|
12
|
+
| `datacircle_best_plans` | One API's plans, sorted by score out of 100, best first. Each plan comes with a rank and a price per 1,000 calls | `GET /apis/{slug}/best` |
|
|
13
|
+
| `datacircle_search_plans` | Plans that match a provider or plan name, on all APIs or on one API. You can sort them by score, provider or price | `GET /plans` |
|
|
14
|
+
| `datacircle_provider` | The APIs a provider sells, and the provider's rank on each API | `GET /providers/{slug}` |
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
bundle add mcp-datacircle
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The gem needs Ruby 3.2 or later and `mcp` 0.4.0 or later.
|
|
23
|
+
|
|
24
|
+
## Add the tools to your server
|
|
25
|
+
|
|
26
|
+
**server.rb**
|
|
27
|
+
|
|
28
|
+
```ruby
|
|
29
|
+
require "mcp"
|
|
30
|
+
require "mcp/datacircle"
|
|
31
|
+
|
|
32
|
+
server = MCP::Server.new(name: "my_server", tools: MCP::Datacircle.tools)
|
|
33
|
+
MCP::Server::Transports::StdioTransport.new(server).open
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Add your own tools to the list too, like `tools: [*MCP::Datacircle.tools, MyTool]`. To add one tool alone, give its class, like `tools: [MCP::Datacircle::BestPlans]`. The tools work the same over the SDK's Streamable HTTP transport.
|
|
37
|
+
|
|
38
|
+
To try the server, open the MCP Inspector:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx @modelcontextprotocol/inspector ruby server.rb
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Serve the tools alone
|
|
45
|
+
|
|
46
|
+
The gem comes with a command that serves the four tools on stdio:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
gem install mcp-datacircle
|
|
50
|
+
mcp-datacircle
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Set your MCP client to start the command `mcp-datacircle`.
|
|
54
|
+
|
|
55
|
+
## What the model reads
|
|
56
|
+
|
|
57
|
+
Each tool gives a JSON object, as text and as structured content. Each plan comes with a rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and a page on datacircle.dev. That page lists every field.
|
|
58
|
+
|
|
59
|
+
For an unknown slug, the tool gives an error result with the API's message, as `{"error": "..."}`. If the network fails, the error gives the network's message. The model can then call the tool again and keep going. The SDK checks the arguments against each tool's input schema before the tool runs. If the arguments are wrong, the model gets the SDK's error.
|
|
60
|
+
|
|
61
|
+
The annotations mark all four tools as read only.
|
|
62
|
+
|
|
63
|
+
## Call a tool yourself
|
|
64
|
+
|
|
65
|
+
You can call each tool from Ruby without running a server:
|
|
66
|
+
|
|
67
|
+
```ruby
|
|
68
|
+
require "mcp/datacircle"
|
|
69
|
+
|
|
70
|
+
response = MCP::Datacircle::BestPlans.call(slug: "email-finder", limit: 3)
|
|
71
|
+
puts response.structured_content["plans"].map { |plan| plan["provider"] }
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Network
|
|
75
|
+
|
|
76
|
+
Each tool call sends HTTPS GET requests to https://api.datacircle.dev/v1 and nowhere else. Most calls send one request. A call sends up to three when the first finds nothing, like when the model gives a name in place of a slug. The requests hold only the tool's own arguments: no key and nothing from your chats. The API takes up to 60 calls a minute from one IP address. The tool waits once, for a minute at most, when the API says to wait. The gem depends only on `mcp`, and it stores nothing.
|
|
77
|
+
|
|
78
|
+
## Links
|
|
79
|
+
|
|
80
|
+
- Datacircle: https://datacircle.dev
|
|
81
|
+
- The API: https://datacircle.dev/api
|
|
82
|
+
- The API's spec: https://api.datacircle.dev/v1/openapi.json
|
|
83
|
+
- What each key means: https://datacircle.dev/fields
|
|
84
|
+
|
|
85
|
+
MIT license.
|
data/exe/mcp-datacircle
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module MCP
|
|
4
|
+
module Datacircle
|
|
5
|
+
# A plan holds about 90 keys (its terms of use, its aggregators...): these choose a plan, the rest is on its page.
|
|
6
|
+
PLAN_KEYS = %w[api rank provider plan score perThousand notFoundPerThousand billing pay currency units unit
|
|
7
|
+
strengths latencyMs page pricingPage docs].freeze
|
|
8
|
+
|
|
9
|
+
# Where a provider's plans are, for a model that sent a provider's name to an API's tool.
|
|
10
|
+
FOR_PROVIDER = "A provider's plans: datacircle_search_plans with its name as query, like bright data, " \
|
|
11
|
+
'or datacircle_provider.'
|
|
12
|
+
|
|
13
|
+
PRICE = "perThousand is a plan's price of 1,000 items in dollars, pay the plan's whole price in its currency."
|
|
14
|
+
|
|
15
|
+
# The four calls of https://api.datacircle.dev/v1 behind the tools, each answering a Hash. Each raises Error when the
|
|
16
|
+
# API gives no data: the tools answer it as {"error" => ...}.
|
|
17
|
+
class Calls
|
|
18
|
+
def initialize(base_url: Client::BASE)
|
|
19
|
+
@client = Client.new(base_url: base_url)
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
# GET /apis, the APIs whose name or slug holds the most of the query's words first.
|
|
23
|
+
def list_apis(query: nil, limit: nil)
|
|
24
|
+
apis = @client.get('/apis')
|
|
25
|
+
words = query.to_s.downcase.tr('-', ' ').split
|
|
26
|
+
held = apis.each_with_index.filter_map do |api, index|
|
|
27
|
+
name = "#{api['api']} #{api['slug'].to_s.tr('-', ' ')}".downcase
|
|
28
|
+
matched = words.count { |word| name.include?(word) }
|
|
29
|
+
[-matched, index, api] if matched.positive? || words.empty?
|
|
30
|
+
end.sort_by { |matched, index, _| [matched, index] }
|
|
31
|
+
note = nil
|
|
32
|
+
if words.any? && (held.empty? || -held.first.first < words.size)
|
|
33
|
+
# A provider's name sent as an API's, like Bright Data, or a question: where its plans are, and the sheet's
|
|
34
|
+
# order when no API holds a word of it.
|
|
35
|
+
note = "No API's name holds every word of #{query.to_s.strip.inspect}. #{FOR_PROVIDER}"
|
|
36
|
+
if held.empty?
|
|
37
|
+
held = apis.each_with_index.map { |api, index| [0, index, api] }
|
|
38
|
+
note += " These are the sheet's APIs in its order."
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
found = { 'total' => held.size,
|
|
42
|
+
'apis' => held.first(number(limit, 1, 200) || 20).map { |_, _, api| brief(api, %w[api slug plans providers best bestPage sheetPage]) } }
|
|
43
|
+
note ? { 'note' => note }.merge(found) : found
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# GET /apis/{slug}/best
|
|
47
|
+
def best_plans(slug: nil, limit: nil)
|
|
48
|
+
api = slugify(slug)
|
|
49
|
+
return { 'error' => "Give an API's slug, like email-finder: datacircle_list_apis gives every slug. #{FOR_PROVIDER}" } if api.empty?
|
|
50
|
+
|
|
51
|
+
begin
|
|
52
|
+
found = @client.get("/apis/#{api}/best", limit: number(limit, 1, 50))
|
|
53
|
+
rescue Error => e
|
|
54
|
+
raise unless e.status == 404
|
|
55
|
+
|
|
56
|
+
# An API's name sent as its slug, like Employee email: the API of that name.
|
|
57
|
+
named = @client.get('/apis').find { |entry| slugify(entry['api']) == api }
|
|
58
|
+
# A provider's name sent as the API's slug: the API's words, and where a provider's plans are.
|
|
59
|
+
return { 'error' => "#{e.message}. datacircle_list_apis gives every API's slug. #{FOR_PROVIDER}" } unless named
|
|
60
|
+
|
|
61
|
+
found = @client.get("/apis/#{named['slug']}/best", limit: number(limit, 1, 50))
|
|
62
|
+
end
|
|
63
|
+
found.merge('plans' => Array(found['plans']).map { |plan| brief(plan) })
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# GET /plans
|
|
67
|
+
def search_plans(query: nil, api: nil, sort: nil, limit: nil, offset: nil)
|
|
68
|
+
notes = []
|
|
69
|
+
begin
|
|
70
|
+
found = search(api, query, sort, limit, offset)
|
|
71
|
+
rescue Error => e
|
|
72
|
+
raise unless e.status == 400 && e.message.include?('api must be') && query.to_s.strip.empty?
|
|
73
|
+
|
|
74
|
+
# A provider's name sent as the API: the plans whose provider or plan name holds it.
|
|
75
|
+
api, query = nil, api
|
|
76
|
+
found = search(api, query, sort, limit, offset)
|
|
77
|
+
notes << "No API is named #{query.to_s.strip.inspect}: these are the plans whose provider or plan name holds it."
|
|
78
|
+
end
|
|
79
|
+
if found['total'].to_i.zero? && query.to_s.include?('-')
|
|
80
|
+
# A slug sent as a name, like bright-data, which no name holds: its words, like bright data. A name with a
|
|
81
|
+
# hyphen, like A-Leads, is found as it is first.
|
|
82
|
+
words = query.to_s.tr('-', ' ').split.join(' ')
|
|
83
|
+
found = search(api, words, sort, limit, offset)
|
|
84
|
+
notes << "No provider's or plan's name holds #{query.to_s.strip.inspect}: these are the plans whose name holds #{words.inspect}."
|
|
85
|
+
end
|
|
86
|
+
found = found.merge('plans' => Array(found['plans']).map { |plan| brief(plan) })
|
|
87
|
+
notes.empty? ? found : { 'note' => notes.join(' ') }.merge(found)
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
# GET /providers/{slug}
|
|
91
|
+
def provider(slug: nil)
|
|
92
|
+
name = slugify(slug)
|
|
93
|
+
return { 'error' => "Give a provider's slug or name, like bright-data or Bright Data" } if name.empty?
|
|
94
|
+
|
|
95
|
+
begin
|
|
96
|
+
found = @client.get("/providers/#{name}")
|
|
97
|
+
rescue Error => e
|
|
98
|
+
raise unless e.status == 404
|
|
99
|
+
|
|
100
|
+
return { 'error' => "#{e.message.split(':').first}. A provider's plans by its name: datacircle_search_plans with " \
|
|
101
|
+
'words of its name as query, like bright data.' }
|
|
102
|
+
end
|
|
103
|
+
apis = Array(found['apis']).map do |entry|
|
|
104
|
+
plans = Array(entry['plans'])
|
|
105
|
+
brief(entry, %w[api slug rank bestPage]).merge('plans' => plans.size, 'best' => best(plans)).compact
|
|
106
|
+
end
|
|
107
|
+
# Its best rank first, the APIs where it has none last, in the API's order.
|
|
108
|
+
apis = apis.each_with_index.sort_by { |entry, index| [entry['rank'].is_a?(Numeric) ? entry['rank'] : Float::INFINITY, index] }.map(&:first)
|
|
109
|
+
found.merge('apis' => apis, 'total' => apis.size, 'ranked' => apis.count { |entry| entry['rank'].is_a?(Numeric) })
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
private
|
|
113
|
+
|
|
114
|
+
def search(api, query, sort, limit, offset)
|
|
115
|
+
@client.get('/plans', api: api.to_s.strip, query: query.to_s.strip,
|
|
116
|
+
sort: (sort.to_s if %w[score provider price].include?(sort.to_s)),
|
|
117
|
+
limit: number(limit, 1, 50), offset: number(offset, 0, 1_000_000))
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
def brief(item, keys = PLAN_KEYS)
|
|
121
|
+
keys.each_with_object({}) { |key, kept| kept[key] = item[key] unless item[key].nil? }
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
# A number the model sent, within the API's range, or nil when it sent none.
|
|
125
|
+
def number(value, low, high)
|
|
126
|
+
return nil if value.nil? || value.to_s.strip.empty?
|
|
127
|
+
return value.to_i.clamp(low, high) if value.is_a?(Numeric)
|
|
128
|
+
|
|
129
|
+
Integer(value.to_s.strip, 10).clamp(low, high)
|
|
130
|
+
rescue ArgumentError
|
|
131
|
+
nil
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
# The API's rule for a slug: the name in lowercase letters and digits, the rest a hyphen.
|
|
135
|
+
def slugify(value)
|
|
136
|
+
value.to_s.strip.downcase.unicode_normalize(:nfkd).gsub(/\p{Mn}/, '').gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
# A provider's best plan on an API: its lowest rank, else its first.
|
|
140
|
+
def best(plans)
|
|
141
|
+
top = plans.select { |plan| plan['rank'].is_a?(Numeric) }.min_by { |plan| plan['rank'] } || plans.first
|
|
142
|
+
top && brief(top, %w[plan score perThousand page])
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
end
|
|
146
|
+
end
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'json'
|
|
4
|
+
require 'net/http'
|
|
5
|
+
require 'uri'
|
|
6
|
+
|
|
7
|
+
module MCP
|
|
8
|
+
module Datacircle
|
|
9
|
+
# What Datacircle's API answered when it gave no data (its HTTP status in #status), or why it could not be reached.
|
|
10
|
+
class Error < StandardError
|
|
11
|
+
attr_reader :status
|
|
12
|
+
|
|
13
|
+
def initialize(message = nil, status: nil)
|
|
14
|
+
super(message)
|
|
15
|
+
@status = status
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# One HTTPS GET to Datacircle's open API, with no key: its answer as a Hash or an Array.
|
|
20
|
+
class Client
|
|
21
|
+
BASE = 'https://api.datacircle.dev/v1'
|
|
22
|
+
|
|
23
|
+
def initialize(base_url: BASE)
|
|
24
|
+
@base = base_url.to_s.chomp('/')
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
def get(path, params = {})
|
|
28
|
+
uri = URI("#{@base}#{path}")
|
|
29
|
+
query = params.reject { |_, value| value.nil? || value.to_s.strip.empty? }
|
|
30
|
+
uri.query = URI.encode_www_form(query) unless query.empty?
|
|
31
|
+
2.times do |attempt|
|
|
32
|
+
response = request(uri)
|
|
33
|
+
return parse(response) if response.is_a?(Net::HTTPSuccess)
|
|
34
|
+
|
|
35
|
+
if response.code == '429' && attempt.zero?
|
|
36
|
+
sleep(wait(response))
|
|
37
|
+
next
|
|
38
|
+
end
|
|
39
|
+
raise Error.new(words(response), status: response.code.to_i)
|
|
40
|
+
end
|
|
41
|
+
raise Error.new("Datacircle's API answered 429 twice: wait a minute and call again", status: 429)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
private
|
|
45
|
+
|
|
46
|
+
def request(uri)
|
|
47
|
+
Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 15, read_timeout: 30) do |http|
|
|
48
|
+
http.get(uri.request_uri, 'Accept' => 'application/json', 'User-Agent' => "mcp-datacircle/#{VERSION}")
|
|
49
|
+
end
|
|
50
|
+
rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
|
|
51
|
+
raise Error, "Datacircle's API could not be reached: #{e.message}"
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def parse(response)
|
|
55
|
+
JSON.parse(response.body.to_s)
|
|
56
|
+
rescue JSON::ParserError
|
|
57
|
+
raise Error.new("Datacircle's API answered #{response.code} with no JSON", status: response.code.to_i)
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# The API asks to wait in Retry-After: its seconds, a minute at most.
|
|
61
|
+
def wait(response)
|
|
62
|
+
Integer(response['Retry-After'] || 30).clamp(1, 60)
|
|
63
|
+
rescue ArgumentError
|
|
64
|
+
30
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# The API's own words: its error of a 4xx, else its status.
|
|
68
|
+
def words(response)
|
|
69
|
+
parsed = JSON.parse(response.body.to_s)
|
|
70
|
+
parsed.is_a?(Hash) && parsed['error'] ? parsed['error'].to_s : "Datacircle's API answered #{response.code}"
|
|
71
|
+
rescue JSON::ParserError
|
|
72
|
+
"Datacircle's API answered #{response.code}"
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module MCP
|
|
4
|
+
module Datacircle
|
|
5
|
+
# A tool of Datacircle's open API, read only: its MCP name is datacircle_ and its class's, like datacircle_best_plans.
|
|
6
|
+
class Tool < MCP::Tool
|
|
7
|
+
ANNOTATIONS = { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: true }.freeze
|
|
8
|
+
|
|
9
|
+
class << self
|
|
10
|
+
def inherited(subclass)
|
|
11
|
+
super
|
|
12
|
+
subclass.tool_name("datacircle_#{subclass.name.split('::').last.gsub(/(?<=[a-z])(?=[A-Z])/, '_').downcase}")
|
|
13
|
+
subclass.annotations(ANNOTATIONS)
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
# The answer to an MCP client's tools/call, as the server calls it: the call's JSON as text and as structured
|
|
17
|
+
# content, or the API's error as {"error": ...} with isError, never raised. Arguments it does not take are
|
|
18
|
+
# dropped, a number sent as text is read, one out of range is brought into it.
|
|
19
|
+
def call(server_context: nil, **arguments)
|
|
20
|
+
taken = method(:answer).parameters.filter_map { |type, name| name if type == :key }
|
|
21
|
+
kept = arguments.transform_keys(&:to_sym).slice(*taken).compact
|
|
22
|
+
found = begin
|
|
23
|
+
answer(**kept)
|
|
24
|
+
rescue Error => e
|
|
25
|
+
{ 'error' => e.message }
|
|
26
|
+
end
|
|
27
|
+
MCP::Tool::Response.new([{ type: 'text', text: JSON.generate(found) }], error: found.key?('error'),
|
|
28
|
+
structured_content: found)
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
private
|
|
32
|
+
|
|
33
|
+
def calls
|
|
34
|
+
Calls.new(base_url: Datacircle.base_url)
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
# GET /apis
|
|
40
|
+
class ListApis < Tool
|
|
41
|
+
title "List Datacircle's GTM APIs"
|
|
42
|
+
description "Lists the GTM APIs on Datacircle's sheet (https://datacircle.dev), with each API's slug, how many plans " \
|
|
43
|
+
"and providers it has and its best plan. Call it first to find an API's slug."
|
|
44
|
+
input_schema(
|
|
45
|
+
properties: {
|
|
46
|
+
query: { type: 'string', description: "Words of the API's name or slug, like email or linkedin profile: the " \
|
|
47
|
+
"APIs that hold the most of them come first. The sheet's order when left out." },
|
|
48
|
+
limit: { type: 'integer', minimum: 1, maximum: 200,
|
|
49
|
+
description: 'How many APIs to give, 1 to 200. 20 when left out: the sheet has about 150.' }
|
|
50
|
+
}
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
def self.answer(query: nil, limit: nil)
|
|
54
|
+
calls.list_apis(query: query, limit: limit)
|
|
55
|
+
end
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# GET /apis/{slug}/best
|
|
59
|
+
class BestPlans < Tool
|
|
60
|
+
title "An API's best plans"
|
|
61
|
+
description "Gives an API's plans best first by their score out of 100 on Datacircle's benchmark " \
|
|
62
|
+
'(https://datacircle.dev), each with its rank, provider, plan, $ per 1,000 calls and its page. ' \
|
|
63
|
+
"#{PRICE}"
|
|
64
|
+
input_schema(
|
|
65
|
+
properties: {
|
|
66
|
+
slug: { type: 'string', description: "The API's slug, like email-finder or linkedin-profile, as " \
|
|
67
|
+
'datacircle_list_apis gives it.' },
|
|
68
|
+
limit: { type: 'integer', minimum: 1, maximum: 50, description: 'How many plans to give, 1 to 50. 10 when left out.' }
|
|
69
|
+
},
|
|
70
|
+
required: ['slug']
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
def self.answer(slug: nil, limit: nil)
|
|
74
|
+
calls.best_plans(slug: slug, limit: limit)
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
# GET /plans
|
|
79
|
+
class SearchPlans < Tool
|
|
80
|
+
title "Search Datacircle's plans"
|
|
81
|
+
description "Searches every plan on Datacircle's sheet (https://datacircle.dev), or one API's, by provider or plan " \
|
|
82
|
+
'name, sorted by score, provider or price. Gives how many were found and up to limit of them. ' \
|
|
83
|
+
"#{PRICE}"
|
|
84
|
+
input_schema(
|
|
85
|
+
properties: {
|
|
86
|
+
query: { type: 'string', description: "Words that must all appear in the provider's or plan's name, like bright data." },
|
|
87
|
+
api: { type: 'string', description: "Only this API's plans: its name or slug, like email-finder. A provider's " \
|
|
88
|
+
'name goes in query, never here. Every API when left out.' },
|
|
89
|
+
sort: { type: 'string', enum: %w[score provider price],
|
|
90
|
+
description: 'score (best first, the default), provider (A to Z) or price ($ per 1,000, lowest first).' },
|
|
91
|
+
limit: { type: 'integer', minimum: 1, maximum: 50, description: 'How many plans to give, 1 to 50. 10 when left out.' },
|
|
92
|
+
offset: { type: 'integer', minimum: 0, description: 'How many found plans to skip first. 0 when left out.' }
|
|
93
|
+
}
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
def self.answer(query: nil, api: nil, sort: nil, limit: nil, offset: nil)
|
|
97
|
+
calls.search_plans(query: query, api: api, sort: sort, limit: limit, offset: offset)
|
|
98
|
+
end
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
# GET /providers/{slug}
|
|
102
|
+
class Provider < Tool
|
|
103
|
+
title "A provider's ranks"
|
|
104
|
+
description "Gives each API one provider sells and its rank on each on Datacircle's benchmark " \
|
|
105
|
+
'(https://datacircle.dev), with its best plan there, its best rank first. total is how many APIs it ' \
|
|
106
|
+
'sells, ranked on how many of them it has a rank.'
|
|
107
|
+
input_schema(
|
|
108
|
+
properties: {
|
|
109
|
+
slug: { type: 'string', description: "The provider's slug, like bright-data, or its name, like Bright Data: " \
|
|
110
|
+
'the name is made a slug.' }
|
|
111
|
+
},
|
|
112
|
+
required: ['slug']
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
def self.answer(slug: nil)
|
|
116
|
+
calls.provider(slug: slug)
|
|
117
|
+
end
|
|
118
|
+
end
|
|
119
|
+
end
|
|
120
|
+
end
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'json'
|
|
4
|
+
require 'mcp'
|
|
5
|
+
require_relative 'datacircle/version'
|
|
6
|
+
require_relative 'datacircle/client'
|
|
7
|
+
require_relative 'datacircle/calls'
|
|
8
|
+
require_relative 'datacircle/tools'
|
|
9
|
+
|
|
10
|
+
module MCP
|
|
11
|
+
# Datacircle's open API as four MCP tools, with no key: find the best GTM APIs. We benchmark all the GTM APIs and we
|
|
12
|
+
# put the results on our website, https://datacircle.dev
|
|
13
|
+
#
|
|
14
|
+
# MCP::Server.new(name: "my_server", tools: [*MCP::Datacircle.tools, MyTool])
|
|
15
|
+
#
|
|
16
|
+
# datacircle_list_apis, datacircle_best_plans, datacircle_search_plans and datacircle_provider make one GET of
|
|
17
|
+
# https://api.datacircle.dev/v1 each. Each answers its JSON as text and as structured content; the API's error, or
|
|
18
|
+
# why it could not be reached, is a tool error (isError) for the model to read and call again, never raised.
|
|
19
|
+
module Datacircle
|
|
20
|
+
TOOLS = [ListApis, BestPlans, SearchPlans, Provider].freeze
|
|
21
|
+
|
|
22
|
+
class << self
|
|
23
|
+
# Where the tools call, https://api.datacircle.dev/v1 unless set.
|
|
24
|
+
attr_writer :base_url
|
|
25
|
+
|
|
26
|
+
def base_url
|
|
27
|
+
@base_url || Client::BASE
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# The four tool classes, for an MCP::Server's tools.
|
|
31
|
+
def tools
|
|
32
|
+
TOOLS.dup
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
# An MCP::Server of the four tools alone, named datacircle: options go to MCP::Server.new.
|
|
36
|
+
def server(**options)
|
|
37
|
+
given = { name: 'datacircle', title: 'Datacircle', version: VERSION, tools: tools }
|
|
38
|
+
# website_url came with mcp 0.5.0.
|
|
39
|
+
given[:website_url] = 'https://datacircle.dev' if MCP::Server.instance_method(:initialize).parameters.any? { |_, name| name == :website_url }
|
|
40
|
+
MCP::Server.new(**given, **options)
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: mcp-datacircle
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Wayne Hamadi
|
|
8
|
+
bindir: exe
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: mcp
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - ">="
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: 0.4.0
|
|
19
|
+
- - "<"
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: '2'
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - ">="
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: 0.4.0
|
|
29
|
+
- - "<"
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: '2'
|
|
32
|
+
description: 'Four MCP tools on Datacircle''s open API, with no key, for a server
|
|
33
|
+
of the official MCP Ruby SDK: list the GTM APIs, the best plans of one API, a search
|
|
34
|
+
of every plan and one provider''s ranks. We benchmark all the GTM APIs and we put
|
|
35
|
+
the results on our website: https://datacircle.dev'
|
|
36
|
+
email:
|
|
37
|
+
- wayne@datacircle.dev
|
|
38
|
+
executables:
|
|
39
|
+
- mcp-datacircle
|
|
40
|
+
extensions: []
|
|
41
|
+
extra_rdoc_files: []
|
|
42
|
+
files:
|
|
43
|
+
- LICENSE.txt
|
|
44
|
+
- README.md
|
|
45
|
+
- exe/mcp-datacircle
|
|
46
|
+
- lib/mcp/datacircle.rb
|
|
47
|
+
- lib/mcp/datacircle/calls.rb
|
|
48
|
+
- lib/mcp/datacircle/client.rb
|
|
49
|
+
- lib/mcp/datacircle/tools.rb
|
|
50
|
+
- lib/mcp/datacircle/version.rb
|
|
51
|
+
homepage: https://datacircle.dev
|
|
52
|
+
licenses:
|
|
53
|
+
- MIT
|
|
54
|
+
metadata:
|
|
55
|
+
homepage_uri: https://datacircle.dev
|
|
56
|
+
source_code_uri: https://github.com/waynehamadi/mcp-datacircle-ruby
|
|
57
|
+
documentation_uri: https://github.com/waynehamadi/mcp-datacircle-ruby#readme
|
|
58
|
+
bug_tracker_uri: https://github.com/waynehamadi/mcp-datacircle-ruby/issues
|
|
59
|
+
rdoc_options: []
|
|
60
|
+
require_paths:
|
|
61
|
+
- lib
|
|
62
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
63
|
+
requirements:
|
|
64
|
+
- - ">="
|
|
65
|
+
- !ruby/object:Gem::Version
|
|
66
|
+
version: 3.2.0
|
|
67
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
68
|
+
requirements:
|
|
69
|
+
- - ">="
|
|
70
|
+
- !ruby/object:Gem::Version
|
|
71
|
+
version: '0'
|
|
72
|
+
requirements: []
|
|
73
|
+
rubygems_version: 3.6.9
|
|
74
|
+
specification_version: 4
|
|
75
|
+
summary: Find the best GTM APIs, in an MCP server of the official Ruby SDK.
|
|
76
|
+
test_files: []
|