stack-scout-mcp 0.1.0__tar.gz

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.
@@ -0,0 +1,14 @@
1
+ # Secrets
2
+ .env
3
+ credentials.json
4
+ token.json
5
+
6
+ # Temporary / regenerated files
7
+ .tmp/
8
+
9
+ # Python
10
+ __pycache__/
11
+ *.pyc
12
+ .venv/
13
+ venv/
14
+ *.egg-info/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mhassaan0806-jpg
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.
@@ -0,0 +1,256 @@
1
+ Metadata-Version: 2.5
2
+ Name: stack-scout-mcp
3
+ Version: 0.1.0
4
+ Summary: The honest free-tool finder for AI: an MCP server that finds free, open-source tools for any project and checks they're alive and truly free.
5
+ Project-URL: Homepage, https://github.com/mhassaan0806-jpg/stack-scout-mcp
6
+ Project-URL: Source, https://github.com/mhassaan0806-jpg/stack-scout-mcp
7
+ Project-URL: Issues, https://github.com/mhassaan0806-jpg/stack-scout-mcp/issues
8
+ Author: mhassaan0806-jpg
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude,cursor,developer-tools,license-checker,mcp,mcp-server,model-context-protocol,open-source,open-source-alternatives,tech-stack
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Software Development
22
+ Classifier: Topic :: Software Development :: Libraries
23
+ Requires-Python: >=3.10
24
+ Requires-Dist: mcp<3,>=2.0
25
+ Description-Content-Type: text/markdown
26
+
27
+ # Stack Scout MCP: free open-source tool finder for Claude and Cursor
28
+
29
+ **The honest free-tool finder for your AI.** Describe what you want to build. Get free, open-source
30
+ tools for every part of it: checked to be alive, checked to be truly free, with the catch spelled out.
31
+
32
+ [![tests](https://github.com/mhassaan0806-jpg/stack-scout-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/mhassaan0806-jpg/stack-scout-mcp/actions/workflows/tests.yml)
33
+ ![License: MIT](https://img.shields.io/badge/license-MIT-green)
34
+ ![Cost: free](https://img.shields.io/badge/cost-%240-brightgreen)
35
+
36
+ ## What is Stack Scout? (in simple words)
37
+
38
+ You want to make an app. For example, a shoe shop.
39
+
40
+ Your app needs many parts:
41
+ - a page to log in
42
+ - a shopping cart
43
+ - a way to pay
44
+ - emails
45
+
46
+ You do not need to make every part yourself. People share free parts on the internet.
47
+ But it is hard to find good ones. Some are old. Some are broken. Some say "free", but they are not really free.
48
+
49
+ **Stack Scout helps your AI find the good free parts.**
50
+
51
+ 1. You tell your AI (Claude or Cursor): "I want to make a shoe shop."
52
+ 2. Your AI asks Stack Scout for help.
53
+ 3. Stack Scout looks on GitHub. GitHub is a big website with free code.
54
+ 4. Stack Scout checks every tool. Is it new? Do many people use it? Is it really free? Is there a catch?
55
+ 5. Your AI gives you a short list: the best free tools, with links, good points and bad points.
56
+
57
+ Stack Scout is free. It runs on your computer. You do not pay for anything.
58
+
59
+ ## How it works (for developers)
60
+
61
+ Stack Scout is an MCP server for AI assistants you already use (Claude, Cursor, ...). Your AI splits your
62
+ idea into needs. Stack Scout finds the tools for each need, reads their licenses and READMEs, checks
63
+ activity, downloads, security and community discussion, and hands your AI the facts. Your AI then
64
+ explains the pros, cons and the catch, without guessing from old training data.
65
+
66
+ ## Why "honest"
67
+
68
+ AI assistants often recommend tools that are abandoned, archived, or "open source" in name only. Stack Scout
69
+ checks live data every time. Real examples from testing:
70
+
71
+ | Tool | GitHub says | Stack Scout found |
72
+ |---|---|---|
73
+ | Medusa (e-commerce) | License: "Other" | MIT core, but the Enterprise Edition needs a commercial agreement → **open core** |
74
+ | Meilisearch (search) | License: BUSL (not free) | MIT core, BUSL only for enterprise parts → **open core**, still usable for free |
75
+ | Terraform | License: BUSL | Restrictive → **not recommended** |
76
+ | Sentry | License: "Other" | Functional Source License, turns Apache only after 2 years → **not free today** |
77
+ | Elasticsearch | License: "Other" | You may choose AGPL → **free (copyleft)** |
78
+
79
+ It also skips archived repos, repos with no code changes in 2 years, and awesome-lists or tutorials
80
+ posing as tools.
81
+
82
+ ## Example
83
+
84
+ ```
85
+ > I want to build an online shoe store with TypeScript. Use Stack Scout.
86
+
87
+ ## 1. Shopping cart & product catalog
88
+ | # | Tool | Stars | Last code change | License | Score |
89
+ | 1 | bagisto/bagisto | 28.4k | 3 days ago | MIT (free, permissive) | 96 |
90
+ | 2 | saleor/saleor | 23.6k | 1 day ago | BSD-3-Clause (free, permissive) | 95 |
91
+ | 3 | medusajs/medusa | 37.4k | today | MIT (open core: some parts paid) | 91 |
92
+
93
+ #### medusajs/medusa: research notes
94
+ - README mentions paid terms: "The RBAC-based Enterprise Edition materials ... require a
95
+ commercial agreement with MedusaJS, Inc."
96
+ - Activity: latest release v2.23.0 on 2026-11-20
97
+ - Adoption: package @medusajs/medusa on npm, 1.4M downloads last month
98
+ - Security practices (OpenSSF Scorecard): 5.7/10
99
+ - Known vulnerabilities in latest version: none listed in OSV
100
+ - README mentions (likely setup needs): Docker, PostgreSQL, Redis, Node.js
101
+ ...
102
+ ```
103
+
104
+ It works for anything, not just apps: "a 2D game engine" → Godot, PixiJS, GDevelop;
105
+ "extract text from PDF files in python" → pdfplumber, pdftext.
106
+
107
+ ## Install (one line)
108
+
109
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/), a free Python tool runner.
110
+ It downloads Stack Scout and keeps it updated for you.
111
+
112
+ **Claude Code:**
113
+
114
+ ```bash
115
+ claude mcp add stack-scout -- uvx stack-scout-mcp
116
+ ```
117
+
118
+ **Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json`), **VS Code** and other MCP apps:
119
+
120
+ ```json
121
+ {
122
+ "mcpServers": {
123
+ "stack-scout": {
124
+ "command": "uvx",
125
+ "args": ["stack-scout-mcp"]
126
+ }
127
+ }
128
+ }
129
+ ```
130
+
131
+ Restart the app, then ask: *"Use Stack Scout to find free tools for an online shoe store."*
132
+
133
+ **Optional: more searches.** Without a token, GitHub allows 10 searches a minute. A free
134
+ [GitHub token](https://github.com/settings/tokens) (no permissions needed) raises that to 30. Add it to the config:
135
+
136
+ ```json
137
+ "stack-scout": {
138
+ "command": "uvx",
139
+ "args": ["stack-scout-mcp"],
140
+ "env": { "GITHUB_TOKEN": "your-token" }
141
+ }
142
+ ```
143
+
144
+ ### From source (for contributors)
145
+
146
+ ```bash
147
+ git clone https://github.com/mhassaan0806-jpg/stack-scout-mcp.git && cd stack-scout-mcp
148
+ python -m venv .venv
149
+ .venv/bin/pip install -e . # Windows: .venv\Scripts\pip install -e .
150
+ ```
151
+
152
+ Then point your MCP app at `/full/path/.venv/bin/python` with args `["/full/path/server.py"]`.
153
+ From a clone, a `.env` file (copy `.env.example`) can hold the GitHub token.
154
+
155
+ ## Tools your AI gets
156
+
157
+ | Tool | Use it for |
158
+ |------|------------|
159
+ | `scout_stack` | Researched free tools for every need of a project |
160
+ | `find_tools` | One need ("send emails", "PDF invoices", "2D game engine") |
161
+ | `research_tool` | Vetting a GitHub link: maintained? truly free? what's the catch? |
162
+ | `plan_app_components` | Backup: guess an idea's needs from keywords |
163
+ | `list_building_blocks` | 24 common needs with tuned searches |
164
+
165
+ ## Where the facts come from (all free, no paid keys)
166
+
167
+ GitHub (search, README, LICENSE, releases) · deps.dev (OpenSSF Scorecard, packages) · OSV
168
+ (vulnerabilities) · npm / PyPI / crates.io (downloads) · Hacker News (discussions).
169
+ Everything runs on your computer and the thinking is done by your own AI, so it costs $0 to run.
170
+
171
+ ## Use it without an AI
172
+
173
+ ```bash
174
+ python -m stack_scout_mcp.tools.scout_stack "online shoe store" --language TypeScript
175
+ python -m stack_scout_mcp.tools.scout_stack "pdf tool" --components "extract text from pdf files in python"
176
+ python -m stack_scout_mcp.tools.research_tool medusajs/medusa
177
+ ```
178
+
179
+ ## Tests
180
+
181
+ ```bash
182
+ python -m unittest discover tests # offline, < 1 second
183
+ .venv/bin/python tests/live_mcp_smoke.py # starts the MCP server like Claude does, live data
184
+ ```
185
+
186
+ ## How it's organised
187
+
188
+ ```
189
+ stack_scout_mcp/server.py MCP server: thin wrapper around tools/
190
+ stack_scout_mcp/tools/ Scripts that do the work (search, license, health, research, rank, report)
191
+ stack_scout_mcp/tools/data/ Building-block catalog: add needs here, no code needed
192
+ server.py Runs the server from a clone
193
+ workflows/ Plain-language guides: how to run, evaluate, connect and extend
194
+ tests/ Offline logic tests + a live MCP smoke test
195
+ .tmp/ Cache when running from a clone (safe to delete)
196
+ ```
197
+
198
+ ## Limits (honestly)
199
+
200
+ - Ranking can't judge fit: a popular AI search engine may rank high for "site search". Your AI is told
201
+ to judge fit and say "unknown" rather than guess.
202
+ - README checks are keyword hints ("read in context"), not legal advice.
203
+ - **Payments:** no open-source project makes card processing free. You'll get payment and billing
204
+ platforms that still connect to a processor (Stripe, PayPal...) with per-transaction fees.
205
+ - No web search of its own yet. Your AI can web-search a pick further.
206
+
207
+ ## Contributing
208
+
209
+ The easiest win is a better catalog. See
210
+ [workflows/extend_catalog.md](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/workflows/extend_catalog.md).
211
+ Please run `python -m unittest discover tests` before opening a pull request.
212
+
213
+ ## FAQ
214
+
215
+ **What is Stack Scout?**
216
+ Stack Scout is a free, open-source MCP server that helps AI assistants like Claude and Cursor find free,
217
+ open-source tools for any software project. It checks that each tool is maintained and truly free, and
218
+ explains the catch, such as paid "enterprise" features or license duties.
219
+
220
+ **Is Stack Scout free?**
221
+ Yes. It is MIT-licensed, runs on your own computer, uses your own AI assistant, and only calls free public
222
+ data sources. There is no account, subscription or API bill.
223
+
224
+ **What is an MCP server?**
225
+ MCP (Model Context Protocol) is a standard way to give AI assistants extra tools. An MCP server is a small
226
+ program the AI can call. Claude Desktop, Claude Code, Cursor, VS Code and other apps support MCP.
227
+
228
+ **How is this different from just asking an AI for free tools?**
229
+ An AI answering from memory can suggest tools that are abandoned, archived, or no longer open source.
230
+ Stack Scout checks live data every time: last code change, license file, releases, downloads, security
231
+ score and known vulnerabilities.
232
+
233
+ **Does it find open-source alternatives to paid software?**
234
+ Yes. Describe the need ("an open-source alternative to Shopify", "self-hosted analytics") and it returns
235
+ free, maintained options, with any paid parts flagged.
236
+
237
+ **Does it only work for web apps?**
238
+ No. It works for any need: games ("2D game engine"), data tools ("extract text from PDF files in python"),
239
+ mobile apps, internal tools and more.
240
+
241
+ **Which tools does it reject?**
242
+ Archived projects, projects with no code changes in two years, "source-available" licenses that restrict
243
+ use (BUSL, SSPL, Elastic, FSL), and awesome-lists or tutorials posing as tools.
244
+
245
+ ## Keywords
246
+
247
+ free tool finder, open source alternatives, MCP server, Model Context Protocol, Claude MCP, Cursor MCP,
248
+ tech stack recommendation, open source software discovery, license checker, open core detection,
249
+ self-hosted alternatives, GitHub repository health, free developer tools, AI coding assistant tools
250
+
251
+ ## License
252
+
253
+ [MIT](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/LICENSE)
254
+
255
+ <!-- mcp-name: io.github.mhassaan0806-jpg/stack-scout-mcp -->
256
+ <!-- Above: ownership marker for the official MCP Registry. Keep it. -->
@@ -0,0 +1,230 @@
1
+ # Stack Scout MCP: free open-source tool finder for Claude and Cursor
2
+
3
+ **The honest free-tool finder for your AI.** Describe what you want to build. Get free, open-source
4
+ tools for every part of it: checked to be alive, checked to be truly free, with the catch spelled out.
5
+
6
+ [![tests](https://github.com/mhassaan0806-jpg/stack-scout-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/mhassaan0806-jpg/stack-scout-mcp/actions/workflows/tests.yml)
7
+ ![License: MIT](https://img.shields.io/badge/license-MIT-green)
8
+ ![Cost: free](https://img.shields.io/badge/cost-%240-brightgreen)
9
+
10
+ ## What is Stack Scout? (in simple words)
11
+
12
+ You want to make an app. For example, a shoe shop.
13
+
14
+ Your app needs many parts:
15
+ - a page to log in
16
+ - a shopping cart
17
+ - a way to pay
18
+ - emails
19
+
20
+ You do not need to make every part yourself. People share free parts on the internet.
21
+ But it is hard to find good ones. Some are old. Some are broken. Some say "free", but they are not really free.
22
+
23
+ **Stack Scout helps your AI find the good free parts.**
24
+
25
+ 1. You tell your AI (Claude or Cursor): "I want to make a shoe shop."
26
+ 2. Your AI asks Stack Scout for help.
27
+ 3. Stack Scout looks on GitHub. GitHub is a big website with free code.
28
+ 4. Stack Scout checks every tool. Is it new? Do many people use it? Is it really free? Is there a catch?
29
+ 5. Your AI gives you a short list: the best free tools, with links, good points and bad points.
30
+
31
+ Stack Scout is free. It runs on your computer. You do not pay for anything.
32
+
33
+ ## How it works (for developers)
34
+
35
+ Stack Scout is an MCP server for AI assistants you already use (Claude, Cursor, ...). Your AI splits your
36
+ idea into needs. Stack Scout finds the tools for each need, reads their licenses and READMEs, checks
37
+ activity, downloads, security and community discussion, and hands your AI the facts. Your AI then
38
+ explains the pros, cons and the catch, without guessing from old training data.
39
+
40
+ ## Why "honest"
41
+
42
+ AI assistants often recommend tools that are abandoned, archived, or "open source" in name only. Stack Scout
43
+ checks live data every time. Real examples from testing:
44
+
45
+ | Tool | GitHub says | Stack Scout found |
46
+ |---|---|---|
47
+ | Medusa (e-commerce) | License: "Other" | MIT core, but the Enterprise Edition needs a commercial agreement → **open core** |
48
+ | Meilisearch (search) | License: BUSL (not free) | MIT core, BUSL only for enterprise parts → **open core**, still usable for free |
49
+ | Terraform | License: BUSL | Restrictive → **not recommended** |
50
+ | Sentry | License: "Other" | Functional Source License, turns Apache only after 2 years → **not free today** |
51
+ | Elasticsearch | License: "Other" | You may choose AGPL → **free (copyleft)** |
52
+
53
+ It also skips archived repos, repos with no code changes in 2 years, and awesome-lists or tutorials
54
+ posing as tools.
55
+
56
+ ## Example
57
+
58
+ ```
59
+ > I want to build an online shoe store with TypeScript. Use Stack Scout.
60
+
61
+ ## 1. Shopping cart & product catalog
62
+ | # | Tool | Stars | Last code change | License | Score |
63
+ | 1 | bagisto/bagisto | 28.4k | 3 days ago | MIT (free, permissive) | 96 |
64
+ | 2 | saleor/saleor | 23.6k | 1 day ago | BSD-3-Clause (free, permissive) | 95 |
65
+ | 3 | medusajs/medusa | 37.4k | today | MIT (open core: some parts paid) | 91 |
66
+
67
+ #### medusajs/medusa: research notes
68
+ - README mentions paid terms: "The RBAC-based Enterprise Edition materials ... require a
69
+ commercial agreement with MedusaJS, Inc."
70
+ - Activity: latest release v2.23.0 on 2026-11-20
71
+ - Adoption: package @medusajs/medusa on npm, 1.4M downloads last month
72
+ - Security practices (OpenSSF Scorecard): 5.7/10
73
+ - Known vulnerabilities in latest version: none listed in OSV
74
+ - README mentions (likely setup needs): Docker, PostgreSQL, Redis, Node.js
75
+ ...
76
+ ```
77
+
78
+ It works for anything, not just apps: "a 2D game engine" → Godot, PixiJS, GDevelop;
79
+ "extract text from PDF files in python" → pdfplumber, pdftext.
80
+
81
+ ## Install (one line)
82
+
83
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/), a free Python tool runner.
84
+ It downloads Stack Scout and keeps it updated for you.
85
+
86
+ **Claude Code:**
87
+
88
+ ```bash
89
+ claude mcp add stack-scout -- uvx stack-scout-mcp
90
+ ```
91
+
92
+ **Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json`), **VS Code** and other MCP apps:
93
+
94
+ ```json
95
+ {
96
+ "mcpServers": {
97
+ "stack-scout": {
98
+ "command": "uvx",
99
+ "args": ["stack-scout-mcp"]
100
+ }
101
+ }
102
+ }
103
+ ```
104
+
105
+ Restart the app, then ask: *"Use Stack Scout to find free tools for an online shoe store."*
106
+
107
+ **Optional: more searches.** Without a token, GitHub allows 10 searches a minute. A free
108
+ [GitHub token](https://github.com/settings/tokens) (no permissions needed) raises that to 30. Add it to the config:
109
+
110
+ ```json
111
+ "stack-scout": {
112
+ "command": "uvx",
113
+ "args": ["stack-scout-mcp"],
114
+ "env": { "GITHUB_TOKEN": "your-token" }
115
+ }
116
+ ```
117
+
118
+ ### From source (for contributors)
119
+
120
+ ```bash
121
+ git clone https://github.com/mhassaan0806-jpg/stack-scout-mcp.git && cd stack-scout-mcp
122
+ python -m venv .venv
123
+ .venv/bin/pip install -e . # Windows: .venv\Scripts\pip install -e .
124
+ ```
125
+
126
+ Then point your MCP app at `/full/path/.venv/bin/python` with args `["/full/path/server.py"]`.
127
+ From a clone, a `.env` file (copy `.env.example`) can hold the GitHub token.
128
+
129
+ ## Tools your AI gets
130
+
131
+ | Tool | Use it for |
132
+ |------|------------|
133
+ | `scout_stack` | Researched free tools for every need of a project |
134
+ | `find_tools` | One need ("send emails", "PDF invoices", "2D game engine") |
135
+ | `research_tool` | Vetting a GitHub link: maintained? truly free? what's the catch? |
136
+ | `plan_app_components` | Backup: guess an idea's needs from keywords |
137
+ | `list_building_blocks` | 24 common needs with tuned searches |
138
+
139
+ ## Where the facts come from (all free, no paid keys)
140
+
141
+ GitHub (search, README, LICENSE, releases) · deps.dev (OpenSSF Scorecard, packages) · OSV
142
+ (vulnerabilities) · npm / PyPI / crates.io (downloads) · Hacker News (discussions).
143
+ Everything runs on your computer and the thinking is done by your own AI, so it costs $0 to run.
144
+
145
+ ## Use it without an AI
146
+
147
+ ```bash
148
+ python -m stack_scout_mcp.tools.scout_stack "online shoe store" --language TypeScript
149
+ python -m stack_scout_mcp.tools.scout_stack "pdf tool" --components "extract text from pdf files in python"
150
+ python -m stack_scout_mcp.tools.research_tool medusajs/medusa
151
+ ```
152
+
153
+ ## Tests
154
+
155
+ ```bash
156
+ python -m unittest discover tests # offline, < 1 second
157
+ .venv/bin/python tests/live_mcp_smoke.py # starts the MCP server like Claude does, live data
158
+ ```
159
+
160
+ ## How it's organised
161
+
162
+ ```
163
+ stack_scout_mcp/server.py MCP server: thin wrapper around tools/
164
+ stack_scout_mcp/tools/ Scripts that do the work (search, license, health, research, rank, report)
165
+ stack_scout_mcp/tools/data/ Building-block catalog: add needs here, no code needed
166
+ server.py Runs the server from a clone
167
+ workflows/ Plain-language guides: how to run, evaluate, connect and extend
168
+ tests/ Offline logic tests + a live MCP smoke test
169
+ .tmp/ Cache when running from a clone (safe to delete)
170
+ ```
171
+
172
+ ## Limits (honestly)
173
+
174
+ - Ranking can't judge fit: a popular AI search engine may rank high for "site search". Your AI is told
175
+ to judge fit and say "unknown" rather than guess.
176
+ - README checks are keyword hints ("read in context"), not legal advice.
177
+ - **Payments:** no open-source project makes card processing free. You'll get payment and billing
178
+ platforms that still connect to a processor (Stripe, PayPal...) with per-transaction fees.
179
+ - No web search of its own yet. Your AI can web-search a pick further.
180
+
181
+ ## Contributing
182
+
183
+ The easiest win is a better catalog. See
184
+ [workflows/extend_catalog.md](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/workflows/extend_catalog.md).
185
+ Please run `python -m unittest discover tests` before opening a pull request.
186
+
187
+ ## FAQ
188
+
189
+ **What is Stack Scout?**
190
+ Stack Scout is a free, open-source MCP server that helps AI assistants like Claude and Cursor find free,
191
+ open-source tools for any software project. It checks that each tool is maintained and truly free, and
192
+ explains the catch, such as paid "enterprise" features or license duties.
193
+
194
+ **Is Stack Scout free?**
195
+ Yes. It is MIT-licensed, runs on your own computer, uses your own AI assistant, and only calls free public
196
+ data sources. There is no account, subscription or API bill.
197
+
198
+ **What is an MCP server?**
199
+ MCP (Model Context Protocol) is a standard way to give AI assistants extra tools. An MCP server is a small
200
+ program the AI can call. Claude Desktop, Claude Code, Cursor, VS Code and other apps support MCP.
201
+
202
+ **How is this different from just asking an AI for free tools?**
203
+ An AI answering from memory can suggest tools that are abandoned, archived, or no longer open source.
204
+ Stack Scout checks live data every time: last code change, license file, releases, downloads, security
205
+ score and known vulnerabilities.
206
+
207
+ **Does it find open-source alternatives to paid software?**
208
+ Yes. Describe the need ("an open-source alternative to Shopify", "self-hosted analytics") and it returns
209
+ free, maintained options, with any paid parts flagged.
210
+
211
+ **Does it only work for web apps?**
212
+ No. It works for any need: games ("2D game engine"), data tools ("extract text from PDF files in python"),
213
+ mobile apps, internal tools and more.
214
+
215
+ **Which tools does it reject?**
216
+ Archived projects, projects with no code changes in two years, "source-available" licenses that restrict
217
+ use (BUSL, SSPL, Elastic, FSL), and awesome-lists or tutorials posing as tools.
218
+
219
+ ## Keywords
220
+
221
+ free tool finder, open source alternatives, MCP server, Model Context Protocol, Claude MCP, Cursor MCP,
222
+ tech stack recommendation, open source software discovery, license checker, open core detection,
223
+ self-hosted alternatives, GitHub repository health, free developer tools, AI coding assistant tools
224
+
225
+ ## License
226
+
227
+ [MIT](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/LICENSE)
228
+
229
+ <!-- mcp-name: io.github.mhassaan0806-jpg/stack-scout-mcp -->
230
+ <!-- Above: ownership marker for the official MCP Registry. Keep it. -->
@@ -0,0 +1,24 @@
1
+ # Stack Scout MCP
2
+
3
+ > Stack Scout is a free, open-source (MIT) MCP server that helps AI assistants such as Claude and Cursor find free, open-source tools for any software project. It checks each tool against live data (activity, license file, releases, downloads, OpenSSF Scorecard, known vulnerabilities, Hacker News) and reports the catch, such as open-core paid features or restrictive licenses, so the AI can recommend tools honestly.
4
+
5
+ Key facts:
6
+ - Cost: $0. Runs locally, uses the user's own AI assistant, and calls only free public data sources (GitHub, deps.dev, OSV, npm, PyPI, crates.io, Hacker News).
7
+ - Works for any need: web apps (an online store: cart, payments, login, email), games (a 2D game engine), data tools (extract text from PDF files in Python), and more.
8
+ - Rejects archived projects, projects with no code changes in 2 years, source-available licenses (BUSL, SSPL, Elastic, FSL), and awesome-lists or tutorials.
9
+ - Detects "open core": a free license plus paid enterprise parts (for example Medusa, Meilisearch, PostHog).
10
+ - MCP tools: scout_stack (all needs of a project), find_tools (one need), research_tool (one GitHub repo), plan_app_components, list_building_blocks.
11
+ - Install: Python 3.10+; clone the repo, `pip install -r requirements.txt`, and register `server.py` as a stdio MCP server in Claude Desktop, Claude Code or Cursor.
12
+
13
+ ## Docs
14
+
15
+ - [README](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/README.md): what it is, install, examples, FAQ
16
+ - [How a project is scouted](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/workflows/scout_stack.md)
17
+ - [How a single repo is evaluated](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/workflows/evaluate_repo.md)
18
+ - [Connect to Claude / Cursor](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/workflows/connect_mcp_server.md)
19
+ - [Add a building block](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/workflows/extend_catalog.md)
20
+
21
+ ## Code
22
+
23
+ - [stack_scout_mcp/server.py](https://github.com/mhassaan0806-jpg/stack-scout-mcp/blob/main/stack_scout_mcp/server.py): MCP server
24
+ - [stack_scout_mcp/tools/](https://github.com/mhassaan0806-jpg/stack-scout-mcp/tree/main/stack_scout_mcp/tools): search, license, health, research, ranking, report
@@ -0,0 +1,48 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "stack-scout-mcp"
7
+ dynamic = ["version"]
8
+ description = "The honest free-tool finder for AI: an MCP server that finds free, open-source tools for any project and checks they're alive and truly free."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.10"
13
+ authors = [{ name = "mhassaan0806-jpg" }]
14
+ keywords = [
15
+ "mcp", "mcp-server", "model-context-protocol", "claude", "cursor", "open-source",
16
+ "open-source-alternatives", "tech-stack", "license-checker", "developer-tools",
17
+ ]
18
+ classifiers = [
19
+ "Development Status :: 4 - Beta",
20
+ "Environment :: Console",
21
+ "Intended Audience :: Developers",
22
+ "Operating System :: OS Independent",
23
+ "Programming Language :: Python :: 3",
24
+ "Programming Language :: Python :: 3.10",
25
+ "Programming Language :: Python :: 3.11",
26
+ "Programming Language :: Python :: 3.12",
27
+ "Programming Language :: Python :: 3.13",
28
+ "Topic :: Software Development",
29
+ "Topic :: Software Development :: Libraries",
30
+ ]
31
+ dependencies = ["mcp>=2.0,<3"]
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/mhassaan0806-jpg/stack-scout-mcp"
35
+ Source = "https://github.com/mhassaan0806-jpg/stack-scout-mcp"
36
+ Issues = "https://github.com/mhassaan0806-jpg/stack-scout-mcp/issues"
37
+
38
+ [project.scripts]
39
+ stack-scout-mcp = "stack_scout_mcp.server:main"
40
+
41
+ [tool.hatch.version]
42
+ path = "stack_scout_mcp/__init__.py"
43
+
44
+ [tool.hatch.build.targets.wheel]
45
+ packages = ["stack_scout_mcp"]
46
+
47
+ [tool.hatch.build.targets.sdist]
48
+ include = ["stack_scout_mcp", "tests", "server.py", "README.md", "LICENSE", "llms.txt", "requirements.txt"]
@@ -0,0 +1,3 @@
1
+ # The tools in tools/ use only the Python standard library.
2
+ # The MCP server needs the official MCP SDK:
3
+ mcp>=2.0,<3
@@ -0,0 +1,8 @@
1
+ """Run the Stack Scout MCP server from a git clone: python server.py
2
+
3
+ Installed users run `uvx stack-scout-mcp` instead. The code lives in stack_scout_mcp/.
4
+ """
5
+ from stack_scout_mcp.server import main
6
+
7
+ if __name__ == "__main__":
8
+ main()
@@ -0,0 +1,3 @@
1
+ """Stack Scout MCP: the honest free-tool finder for AI assistants."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,4 @@
1
+ """python -m stack_scout_mcp -> run the MCP server over stdio."""
2
+ from .server import main
3
+
4
+ main()