stack-scout-mcp 0.1.0__py3-none-any.whl
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.
- stack_scout_mcp/__init__.py +3 -0
- stack_scout_mcp/__main__.py +4 -0
- stack_scout_mcp/server.py +148 -0
- stack_scout_mcp/tools/__init__.py +1 -0
- stack_scout_mcp/tools/_common.py +112 -0
- stack_scout_mcp/tools/data/components.json +52 -0
- stack_scout_mcp/tools/format_report.py +201 -0
- stack_scout_mcp/tools/github_search.py +94 -0
- stack_scout_mcp/tools/license_check.py +128 -0
- stack_scout_mcp/tools/plan_components.py +79 -0
- stack_scout_mcp/tools/rank_tools.py +66 -0
- stack_scout_mcp/tools/repo_health.py +114 -0
- stack_scout_mcp/tools/research_tool.py +332 -0
- stack_scout_mcp/tools/scout_stack.py +208 -0
- stack_scout_mcp-0.1.0.dist-info/METADATA +256 -0
- stack_scout_mcp-0.1.0.dist-info/RECORD +19 -0
- stack_scout_mcp-0.1.0.dist-info/WHEEL +4 -0
- stack_scout_mcp-0.1.0.dist-info/entry_points.txt +2 -0
- stack_scout_mcp-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
"""Stack Scout MCP server: the honest free-tool finder.
|
|
2
|
+
|
|
3
|
+
Gives an AI assistant (Claude, Cursor, ...) tools to find free, open-source tools for
|
|
4
|
+
anything a user wants to build, check that they are alive and truly free, and collect
|
|
5
|
+
the facts (paid parts, setup needs, adoption, security) to explain the catch honestly.
|
|
6
|
+
|
|
7
|
+
Runs on the user's own computer over stdio; the AI app starts it with
|
|
8
|
+
`uvx stack-scout-mcp` (installed) or `python server.py` (from a clone).
|
|
9
|
+
Setup: see workflows/connect_mcp_server.md
|
|
10
|
+
"""
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from mcp.server.mcpserver import MCPServer
|
|
14
|
+
|
|
15
|
+
from .tools._common import FetchError, RateLimitError
|
|
16
|
+
from .tools.format_report import AI_NOTE, format_component, format_report, format_research
|
|
17
|
+
from .tools.github_search import get_repo
|
|
18
|
+
from .tools.plan_components import list_components, plan_components
|
|
19
|
+
from .tools.repo_health import assess
|
|
20
|
+
from .tools.research_tool import research as research_repo
|
|
21
|
+
from .tools.research_tool import resolve_license
|
|
22
|
+
from .tools.scout_stack import scout, scout_component
|
|
23
|
+
|
|
24
|
+
mcp = MCPServer(
|
|
25
|
+
"stack-scout",
|
|
26
|
+
instructions=(
|
|
27
|
+
"Stack Scout finds free, open-source tools for anything a user wants to build, and checks they are "
|
|
28
|
+
"alive and truly free. When a user describes a project or a need: (1) split it yourself into the "
|
|
29
|
+
"separate needs it has, e.g. an online shoe store needs a product catalog and cart, payments, login, "
|
|
30
|
+
"email; a PDF tool needs text extraction. (2) Call scout_stack with the idea and those needs as plain "
|
|
31
|
+
"words or catalog ids (list_building_blocks). For a single need use find_tools; to vet a specific "
|
|
32
|
+
"GitHub link use research_tool. (3) Write the answer from the returned facts only: for each need, a "
|
|
33
|
+
"recommended pick and why it fits, pros, cons, the catch (paid or open-core parts, license duties, "
|
|
34
|
+
"what it takes to host), and technical limits, with links. Say 'unknown' instead of guessing. If a "
|
|
35
|
+
"well-known paid service is the usual choice, mention it briefly and label it paid. Users can ask "
|
|
36
|
+
"you to web-search a tool further; do that with your own web search."
|
|
37
|
+
),
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _friendly_error(e: Exception) -> str:
|
|
42
|
+
if isinstance(e, RateLimitError):
|
|
43
|
+
return (f"Stack Scout hit GitHub's free rate limit: {e} Wait about a minute and try again "
|
|
44
|
+
"(finished searches are cached), or add a free GITHUB_TOKEN to the .env file.")
|
|
45
|
+
return f"Stack Scout could not reach a data source: {e}"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@mcp.tool()
|
|
49
|
+
def scout_stack(
|
|
50
|
+
idea: str,
|
|
51
|
+
needs: list[str] | None = None,
|
|
52
|
+
language: str | None = None,
|
|
53
|
+
top_n: int = 3,
|
|
54
|
+
research: bool = True,
|
|
55
|
+
) -> str:
|
|
56
|
+
"""Find and research the best free, open-source tools for every need of a project.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
idea: What the user wants to build, in plain words, e.g. "an online shoe store".
|
|
60
|
+
needs: The separate needs you identified, as plain words ("extract text from PDFs",
|
|
61
|
+
"shopping cart") or catalog ids ("auth", "payments"; see list_building_blocks).
|
|
62
|
+
Strongly recommended. If omitted, needs are guessed from keywords in the idea.
|
|
63
|
+
language: Preferred programming language for code libraries, e.g. "TypeScript".
|
|
64
|
+
Self-hosted services (databases, search engines) are not filtered by language.
|
|
65
|
+
top_n: Tools per need (1-5, default 3).
|
|
66
|
+
research: Research each pick in depth (README, license, releases, downloads, security,
|
|
67
|
+
Hacker News). Default true; set false for a quick list.
|
|
68
|
+
|
|
69
|
+
Returns a Markdown report: per need, a ranked table plus research notes per tool.
|
|
70
|
+
"""
|
|
71
|
+
try:
|
|
72
|
+
result = scout(idea, needs, language, max(1, min(top_n, 5)), research=research)
|
|
73
|
+
except (RateLimitError, FetchError) as e:
|
|
74
|
+
return _friendly_error(e)
|
|
75
|
+
return format_report(result)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@mcp.tool()
|
|
79
|
+
def find_tools(need: str, language: str | None = None, top_n: int = 3, research: bool = True) -> str:
|
|
80
|
+
"""Find and research free, open-source tools for ONE need, e.g. "send emails" or "PDF invoices".
|
|
81
|
+
|
|
82
|
+
Args:
|
|
83
|
+
need: Plain words or a catalog id (see list_building_blocks). A language named in the
|
|
84
|
+
words ("...in python") is used as a filter.
|
|
85
|
+
language: Preferred programming language for code libraries.
|
|
86
|
+
top_n: How many tools to return (1-5, default 3).
|
|
87
|
+
research: Research each pick in depth (default true).
|
|
88
|
+
"""
|
|
89
|
+
try:
|
|
90
|
+
result = scout(need, [need], language, max(1, min(top_n, 5)), research=research)
|
|
91
|
+
except (RateLimitError, FetchError) as e:
|
|
92
|
+
return _friendly_error(e)
|
|
93
|
+
comp = result["components"][0]
|
|
94
|
+
return "\n".join(format_component(comp) + ["---", AI_NOTE])
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@mcp.tool()
|
|
98
|
+
def research_tool(repo: str) -> str:
|
|
99
|
+
"""Research one GitHub project in depth: is it maintained, truly free, what's the catch?
|
|
100
|
+
|
|
101
|
+
Covers license (including open-core and restrictive terms read from the LICENSE file),
|
|
102
|
+
paid or cloud mentions in the README, setup needs, latest release, downloads, OpenSSF
|
|
103
|
+
security score, known vulnerabilities and Hacker News discussions.
|
|
104
|
+
|
|
105
|
+
Args:
|
|
106
|
+
repo: "owner/name" or a github.com URL.
|
|
107
|
+
"""
|
|
108
|
+
try:
|
|
109
|
+
data = resolve_license(get_repo(repo))
|
|
110
|
+
except ValueError as e:
|
|
111
|
+
return str(e)
|
|
112
|
+
except (RateLimitError, FetchError) as e:
|
|
113
|
+
return _friendly_error(e)
|
|
114
|
+
health = assess(data)
|
|
115
|
+
verdict = {"ok": "Looks good", "caution": "Usable, with caveats", "rejected": "Not recommended"}[health["status"]]
|
|
116
|
+
entry = {**data, "health": health, "research": research_repo(data)}
|
|
117
|
+
lines = [f"## {data['full_name']}: {verdict}", "", f"{data['description']} ({data['url']}). Score {health['score']}/100.", ""]
|
|
118
|
+
lines += [f"- **Not recommended because:** {r}" for r in health["rejected_because"]]
|
|
119
|
+
lines += format_research(entry)[2:] # skip its own heading
|
|
120
|
+
lines += ["---", AI_NOTE]
|
|
121
|
+
return "\n".join(lines)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@mcp.tool()
|
|
125
|
+
def plan_app_components(idea: str) -> str:
|
|
126
|
+
"""Backup only: guess an idea's needs from keywords. Prefer splitting the idea yourself."""
|
|
127
|
+
plan = plan_components(idea)
|
|
128
|
+
lines = [f"Building blocks for: {idea}"]
|
|
129
|
+
if plan["archetypes"]:
|
|
130
|
+
lines.append(f"Looks like: {', '.join(plan['archetypes'])}")
|
|
131
|
+
lines += [f"- {c['id']}: {c['name']}. Why: {c['why']}" for c in plan["components"]]
|
|
132
|
+
lines.append("\nReview this, add what's missing in plain words, and pass the list to scout_stack as `needs`.")
|
|
133
|
+
return "\n".join(lines)
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
@mcp.tool()
|
|
137
|
+
def list_building_blocks() -> str:
|
|
138
|
+
"""List the catalog ids with tuned GitHub searches. Any other need can be passed as plain words."""
|
|
139
|
+
return "\n".join(f"- {c['id']}: {c['name']}" for c in list_components())
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def main() -> None:
|
|
143
|
+
"""Console entry point (`stack-scout-mcp`): serve over stdio."""
|
|
144
|
+
mcp.run()
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
if __name__ == "__main__":
|
|
148
|
+
main()
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Stack Scout deterministic tools (Layer 3 of the WAT framework)."""
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
"""Shared helpers for Stack Scout tools: paths, .env loading, cached HTTP GET.
|
|
2
|
+
|
|
3
|
+
Every network call goes through `http_get`, which caches responses in
|
|
4
|
+
`.tmp/cache/` so repeated runs don't burn free API rate limits.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import hashlib
|
|
9
|
+
import json
|
|
10
|
+
import os
|
|
11
|
+
import time
|
|
12
|
+
import urllib.error
|
|
13
|
+
import urllib.request
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
from .. import __version__
|
|
17
|
+
|
|
18
|
+
DATA_DIR = Path(__file__).resolve().parent / "data"
|
|
19
|
+
# The repo root when running from a git clone; site-packages when installed (then unused).
|
|
20
|
+
REPO_ROOT = Path(__file__).resolve().parent.parent.parent
|
|
21
|
+
IN_CLONE = (REPO_ROOT / "pyproject.toml").exists()
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _cache_dir() -> Path:
|
|
25
|
+
"""Clone: <repo>/.tmp/cache (disposable, gitignored). Installed: the user's cache folder."""
|
|
26
|
+
if os.environ.get("STACK_SCOUT_CACHE_DIR"):
|
|
27
|
+
return Path(os.environ["STACK_SCOUT_CACHE_DIR"])
|
|
28
|
+
if IN_CLONE:
|
|
29
|
+
return REPO_ROOT / ".tmp" / "cache"
|
|
30
|
+
base = os.environ.get("LOCALAPPDATA") or os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
|
|
31
|
+
return Path(base) / "stack-scout-mcp" / "cache"
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
CACHE_DIR = _cache_dir()
|
|
35
|
+
|
|
36
|
+
USER_AGENT = f"stack-scout-mcp/{__version__}"
|
|
37
|
+
DEFAULT_TTL = 6 * 60 * 60 # 6 hours
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class RateLimitError(RuntimeError):
|
|
41
|
+
"""A free API said 'slow down'. `reset_at` is a unix timestamp when known."""
|
|
42
|
+
|
|
43
|
+
def __init__(self, message: str, reset_at: int | None = None):
|
|
44
|
+
super().__init__(message)
|
|
45
|
+
self.reset_at = reset_at
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class FetchError(RuntimeError):
|
|
49
|
+
"""Any other HTTP or network failure."""
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
_env_loaded = False
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def load_env() -> None:
|
|
56
|
+
"""Clone only: load KEY=VALUE pairs from <repo>/.env into os.environ (no overrides).
|
|
57
|
+
|
|
58
|
+
Installed users set GITHUB_TOKEN in their AI app's MCP config ("env") instead.
|
|
59
|
+
"""
|
|
60
|
+
global _env_loaded
|
|
61
|
+
if _env_loaded:
|
|
62
|
+
return
|
|
63
|
+
_env_loaded = True
|
|
64
|
+
env_path = REPO_ROOT / ".env"
|
|
65
|
+
if not IN_CLONE or not env_path.exists():
|
|
66
|
+
return
|
|
67
|
+
for raw in env_path.read_text(encoding="utf-8").splitlines():
|
|
68
|
+
line = raw.strip()
|
|
69
|
+
if not line or line.startswith("#") or "=" not in line:
|
|
70
|
+
continue
|
|
71
|
+
key, _, value = line.partition("=")
|
|
72
|
+
key, value = key.strip(), value.strip().strip('"').strip("'")
|
|
73
|
+
if key and value:
|
|
74
|
+
os.environ.setdefault(key, value)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _cache_file(url: str) -> Path:
|
|
78
|
+
return CACHE_DIR / (hashlib.sha256(url.encode("utf-8")).hexdigest()[:32] + ".json")
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def http_get(url: str, headers: dict | None = None, ttl: int = DEFAULT_TTL, timeout: int = 20) -> str:
|
|
82
|
+
"""GET `url` and return the body as text. Cached on disk for `ttl` seconds (0 = no cache)."""
|
|
83
|
+
cache_file = _cache_file(url)
|
|
84
|
+
if ttl > 0 and cache_file.exists():
|
|
85
|
+
try:
|
|
86
|
+
cached = json.loads(cache_file.read_text(encoding="utf-8"))
|
|
87
|
+
if time.time() - cached["fetched_at"] < ttl:
|
|
88
|
+
return cached["body"]
|
|
89
|
+
except (ValueError, KeyError):
|
|
90
|
+
pass # corrupt cache entry: refetch
|
|
91
|
+
|
|
92
|
+
request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, **(headers or {})})
|
|
93
|
+
try:
|
|
94
|
+
with urllib.request.urlopen(request, timeout=timeout) as resp:
|
|
95
|
+
body = resp.read().decode("utf-8", errors="replace")
|
|
96
|
+
except urllib.error.HTTPError as e:
|
|
97
|
+
detail = e.read().decode("utf-8", errors="replace")[:300]
|
|
98
|
+
if e.code == 429 or (e.code == 403 and "rate limit" in detail.lower()):
|
|
99
|
+
reset = e.headers.get("X-RateLimit-Reset")
|
|
100
|
+
reset_at = int(reset) if reset and reset.isdigit() else None
|
|
101
|
+
wait = f" Resets in ~{max(0, reset_at - int(time.time()))}s." if reset_at else ""
|
|
102
|
+
raise RateLimitError(f"Rate limited by {url.split('/')[2]}.{wait}", reset_at) from e
|
|
103
|
+
raise FetchError(f"HTTP {e.code} for {url}: {detail}") from e
|
|
104
|
+
except urllib.error.URLError as e:
|
|
105
|
+
raise FetchError(f"Network error for {url}: {e.reason}") from e
|
|
106
|
+
|
|
107
|
+
if ttl > 0:
|
|
108
|
+
CACHE_DIR.mkdir(parents=True, exist_ok=True)
|
|
109
|
+
cache_file.write_text(
|
|
110
|
+
json.dumps({"url": url, "fetched_at": time.time(), "body": body}), encoding="utf-8"
|
|
111
|
+
)
|
|
112
|
+
return body
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_about": "Building blocks Stack Scout knows how to search for. 'query' is a GitHub search (topic: qualifiers give the cleanest results). 'language_sensitive' = apply the user's language filter (true for code libraries, false for self-hosted services you run beside any stack). 'keywords' match words in the user's idea. Archetypes map common app types to the blocks they usually need.",
|
|
3
|
+
"components": {
|
|
4
|
+
"auth": {"name": "User login & accounts", "query": "topic:authentication", "language_sensitive": true, "keywords": ["login", "log in", "sign in", "signin", "sign up", "signup", "accounts", "auth", "authentication", "members", "membership", "profiles"]},
|
|
5
|
+
"database": {"name": "Database", "query": "topic:database", "language_sensitive": false, "keywords": ["database", "db", "store data", "save data", "records"]},
|
|
6
|
+
"backend_api": {"name": "Ready-made backend (BaaS)", "query": "topic:backend-as-a-service", "language_sensitive": false, "keywords": ["backend", "api", "baas", "firebase", "supabase"]},
|
|
7
|
+
"payments": {"name": "Payments & checkout", "query": "topic:payments -topic:crypto -topic:cryptocurrency -topic:blockchain -topic:web3 -topic:bitcoin", "language_sensitive": false, "keywords": ["payment", "payments", "pay", "checkout", "stripe", "paypal", "donations", "tips"]},
|
|
8
|
+
"billing": {"name": "Subscriptions, billing & invoices", "query": "topic:billing", "language_sensitive": false, "keywords": ["subscription", "subscriptions", "billing", "invoice", "invoices", "invoicing", "recurring", "plans", "pricing tiers"]},
|
|
9
|
+
"ecommerce": {"name": "Shopping cart & product catalog", "query": "topic:ecommerce", "language_sensitive": false, "keywords": ["cart", "shopping cart", "products", "catalog", "inventory", "orders", "store", "shop"]},
|
|
10
|
+
"email": {"name": "Sending email", "query": "topic:smtp -topic:sms", "language_sensitive": false, "keywords": ["email", "emails", "newsletter", "mail", "mailing list", "receipts"]},
|
|
11
|
+
"file_storage": {"name": "File & image uploads / storage", "query": "topic:object-storage", "language_sensitive": false, "keywords": ["upload", "uploads", "files", "images", "photos", "storage", "attachments", "media"]},
|
|
12
|
+
"search": {"name": "Search", "query": "topic:full-text-search", "language_sensitive": false, "keywords": ["search", "find", "filter", "lookup"]},
|
|
13
|
+
"admin_dashboard": {"name": "Admin panel / internal dashboard", "query": "topic:admin-dashboard", "language_sensitive": true, "keywords": ["admin", "admin panel", "dashboard", "back office", "backoffice", "manage"]},
|
|
14
|
+
"cms": {"name": "Content management (CMS)", "query": "topic:headless-cms", "language_sensitive": false, "keywords": ["blog", "cms", "content", "articles", "posts", "pages", "editor"]},
|
|
15
|
+
"analytics": {"name": "Visitor analytics", "query": "topic:web-analytics", "language_sensitive": false, "keywords": ["analytics", "visitors", "traffic", "metrics", "stats", "tracking visitors"]},
|
|
16
|
+
"notifications": {"name": "Notifications (push, in-app, SMS)", "query": "topic:push-notifications", "language_sensitive": false, "keywords": ["notification", "notifications", "push", "alerts", "sms", "reminders"]},
|
|
17
|
+
"realtime_chat": {"name": "Chat & real-time messaging", "query": "topic:chat -topic:llm -topic:ai -topic:chatgpt -topic:ai-chat", "language_sensitive": false, "keywords": ["chat", "messaging", "messages", "messenger", "dm", "real-time", "realtime", "live"]},
|
|
18
|
+
"comments": {"name": "Comments & discussions", "query": "topic:comments", "language_sensitive": false, "keywords": ["comments", "comment", "discussion", "reviews", "ratings", "feedback"]},
|
|
19
|
+
"forms": {"name": "Forms & surveys", "query": "topic:forms", "language_sensitive": true , "keywords": ["form", "forms", "survey", "surveys", "questionnaire", "quiz"]},
|
|
20
|
+
"scheduling": {"name": "Booking & scheduling", "query": "topic:appointment-scheduling", "language_sensitive": false, "keywords": ["booking", "bookings", "appointment", "appointments", "schedule", "scheduling", "calendar", "reservation", "reservations"]},
|
|
21
|
+
"maps": {"name": "Maps & location", "query": "topic:maps", "language_sensitive": true, "keywords": ["map", "maps", "location", "locations", "gps", "nearby", "directions", "delivery tracking"]},
|
|
22
|
+
"video": {"name": "Video hosting & player", "query": "topic:video-player", "language_sensitive": false, "keywords": ["video", "videos", "stream", "streaming", "player", "courses"]},
|
|
23
|
+
"ui_components": {"name": "UI component library", "query": "topic:ui-components", "language_sensitive": true, "keywords": ["ui", "design system", "components", "buttons", "theme", "frontend"]},
|
|
24
|
+
"background_jobs": {"name": "Background jobs & queues", "query": "topic:job-queue", "language_sensitive": true, "keywords": ["background job", "background jobs", "queue", "queues", "cron", "scheduled tasks", "worker"]},
|
|
25
|
+
"monitoring": {"name": "Error tracking & monitoring", "query": "topic:error-monitoring", "language_sensitive": false, "keywords": ["errors", "error tracking", "monitoring", "logs", "logging", "uptime", "crash"]},
|
|
26
|
+
"feature_flags": {"name": "Feature flags & A/B tests", "query": "topic:feature-flags", "language_sensitive": false, "keywords": ["feature flag", "feature flags", "a/b test", "ab test", "experiments", "rollout"]},
|
|
27
|
+
"i18n": {"name": "Translations (multi-language)", "query": "topic:i18n topic:localization", "language_sensitive": true, "keywords": ["translation", "translations", "multi-language", "multilingual", "languages", "i18n", "localization"]}
|
|
28
|
+
},
|
|
29
|
+
"archetypes": {
|
|
30
|
+
"online store": {"keywords": ["store", "shop", "ecommerce", "e-commerce", "sell", "selling", "merch", "retail", "boutique"],
|
|
31
|
+
"components": ["ecommerce", "payments", "auth", "database", "email", "search", "file_storage", "admin_dashboard", "analytics"]},
|
|
32
|
+
"saas product": {"keywords": ["saas", "subscription", "b2b", "startup", "workspace", "teams"],
|
|
33
|
+
"components": ["auth", "database", "billing", "payments", "email", "admin_dashboard", "analytics", "feature_flags", "monitoring", "background_jobs"]},
|
|
34
|
+
"content site": {"keywords": ["blog", "news", "magazine", "articles", "documentation", "docs", "portfolio", "podcast"],
|
|
35
|
+
"components": ["cms", "search", "comments", "analytics", "email"]},
|
|
36
|
+
"community / social": {"keywords": ["social", "community", "forum", "social network", "followers", "feed", "dating"],
|
|
37
|
+
"components": ["auth", "database", "file_storage", "realtime_chat", "notifications", "comments", "search", "monitoring"]},
|
|
38
|
+
"marketplace": {"keywords": ["marketplace", "buyers", "sellers", "listings", "freelance", "freelancers", "rental", "classifieds"],
|
|
39
|
+
"components": ["auth", "database", "payments", "search", "file_storage", "realtime_chat", "notifications", "email", "admin_dashboard"]},
|
|
40
|
+
"booking app": {"keywords": ["booking", "appointment", "appointments", "reservation", "salon", "clinic", "restaurant", "gym", "tutor", "tutoring"],
|
|
41
|
+
"components": ["scheduling", "auth", "payments", "email", "notifications", "maps", "admin_dashboard"]},
|
|
42
|
+
"messaging app": {"keywords": ["chat app", "messaging", "messenger", "support desk", "helpdesk", "customer support"],
|
|
43
|
+
"components": ["realtime_chat", "auth", "notifications", "file_storage", "database"]},
|
|
44
|
+
"internal tool": {"keywords": ["internal tool", "crm", "inventory", "erp", "reporting", "back office", "dashboard"],
|
|
45
|
+
"components": ["admin_dashboard", "database", "auth", "forms", "analytics"]},
|
|
46
|
+
"learning platform": {"keywords": ["course", "courses", "learning", "lms", "education", "school", "students", "teachers"],
|
|
47
|
+
"components": ["video", "auth", "payments", "cms", "file_storage", "email", "forms"]},
|
|
48
|
+
"delivery / travel": {"keywords": ["delivery", "ride", "rides", "taxi", "tracking", "travel", "trips", "food delivery", "logistics"],
|
|
49
|
+
"components": ["maps", "auth", "payments", "notifications", "realtime_chat", "database", "admin_dashboard"]}
|
|
50
|
+
},
|
|
51
|
+
"default_components": ["auth", "database", "email", "file_storage", "analytics"]
|
|
52
|
+
}
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
"""Turn scout / research results (dicts) into Markdown the user's AI can read and build on.
|
|
2
|
+
|
|
3
|
+
The report holds facts only. The closing "For the AI" note tells the assistant
|
|
4
|
+
to write the pros, cons, catch and fit from these facts, not from memory.
|
|
5
|
+
|
|
6
|
+
CLI (reads the JSON written by `scout_stack.py --json`):
|
|
7
|
+
python -m stack_scout_mcp.tools.format_report .tmp/scout_result.json
|
|
8
|
+
"""
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import sys
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
AI_NOTE = (
|
|
16
|
+
"**For the AI presenting this:** for each need, recommend one pick and say why it fits this project. "
|
|
17
|
+
"Give honest pros, cons, the catch (paid parts, license duties, hosting it needs), and technical limits, "
|
|
18
|
+
"using only the facts above and the linked pages. Say \"unknown\" rather than guess. If a well-known "
|
|
19
|
+
"paid service is the usual choice for a need, mention it briefly and label it paid."
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
CATEGORY_LABEL = {
|
|
23
|
+
"permissive": "free, permissive",
|
|
24
|
+
"weak-copyleft": "free, weak copyleft",
|
|
25
|
+
"copyleft": "free, copyleft",
|
|
26
|
+
"open-core": "open core: some parts paid",
|
|
27
|
+
"unknown": "unclear",
|
|
28
|
+
"not-free": "not free",
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _num(n: int) -> str:
|
|
33
|
+
for size, suffix in ((1_000_000_000, "B"), (1_000_000, "M"), (1000, "k")):
|
|
34
|
+
if n >= size:
|
|
35
|
+
return f"{n / size:.1f}{suffix}".replace(f".0{suffix}", suffix)
|
|
36
|
+
return str(n)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _age(days: int | None) -> str:
|
|
40
|
+
if days is None:
|
|
41
|
+
return "unknown"
|
|
42
|
+
if days < 1:
|
|
43
|
+
return "today"
|
|
44
|
+
if days < 60:
|
|
45
|
+
return f"{days} day{'s' if days != 1 else ''} ago"
|
|
46
|
+
if days < 730:
|
|
47
|
+
return f"{days // 30} months ago"
|
|
48
|
+
return f"{days // 365} years ago"
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _cell(text: str, width: int = 90) -> str:
|
|
52
|
+
text = " ".join((text or "").split()).replace("|", "\\|")
|
|
53
|
+
return text if len(text) <= width else text[: width - 1].rstrip() + "…"
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _license_text(health: dict) -> str:
|
|
57
|
+
lic = health["license"]
|
|
58
|
+
return f"{lic['spdx'] or 'none found'} ({CATEGORY_LABEL[lic['category']]})"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def format_repo_table(repos: list[dict]) -> list[str]:
|
|
62
|
+
lines = [
|
|
63
|
+
"| # | Tool | What it is | Stars | Last code change | License | Score |",
|
|
64
|
+
"|---|------|------------|-------|------------------|---------|-------|",
|
|
65
|
+
]
|
|
66
|
+
for i, r in enumerate(repos, 1):
|
|
67
|
+
h = r["health"]
|
|
68
|
+
lines.append(
|
|
69
|
+
f"| {i} | [{r['full_name']}]({r['url']}) | {_cell(r['description'])} | {_num(r['stars'])} "
|
|
70
|
+
f"| {_age(h['days_since_push'])} | {_license_text(h)} | {h['score']} |"
|
|
71
|
+
)
|
|
72
|
+
return lines
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def format_research(repo: dict) -> list[str]:
|
|
76
|
+
"""Research notes for one repo (needs repo['health'] and repo['research'])."""
|
|
77
|
+
h, notes = repo["health"], repo.get("research") or {}
|
|
78
|
+
lic = h["license"]
|
|
79
|
+
lines = [f"#### {repo['full_name']}: research notes", ""]
|
|
80
|
+
if repo.get("homepage"):
|
|
81
|
+
lines.append(f"- **Website:** {repo['homepage']}")
|
|
82
|
+
lines.append(f"- **License:** {_license_text(h)}. {lic['note']}"
|
|
83
|
+
+ (" (read from the LICENSE file)" if lic.get("detected_from") else ""))
|
|
84
|
+
|
|
85
|
+
readme = notes.get("readme")
|
|
86
|
+
if readme and readme["paid_mentions"]:
|
|
87
|
+
lines.append("- **README mentions paid / cloud / enterprise terms** (read in context):")
|
|
88
|
+
lines += [f" - \"{m}\"" for m in readme["paid_mentions"]]
|
|
89
|
+
|
|
90
|
+
activity = [f"last code change {_age(h['days_since_push'])}"]
|
|
91
|
+
rel = notes.get("latest_release")
|
|
92
|
+
if rel:
|
|
93
|
+
activity.append(f"latest release {rel['title'] or '(untitled)'} on {rel['date']}")
|
|
94
|
+
activity.append(f"{_num(repo.get('open_issues', 0))} open issues and PRs")
|
|
95
|
+
lines.append(f"- **Activity:** {', '.join(activity)}")
|
|
96
|
+
|
|
97
|
+
adoption = [f"{_num(repo['stars'])} GitHub stars"]
|
|
98
|
+
pkg = notes.get("package")
|
|
99
|
+
if pkg:
|
|
100
|
+
dl = pkg.get("downloads")
|
|
101
|
+
dl_text = f", {_num(dl['count'])} downloads {dl['period']}" if dl else ""
|
|
102
|
+
adoption.append(f"package `{pkg['name']}` on {pkg['system'].lower()}{dl_text}")
|
|
103
|
+
lines.append(f"- **Adoption:** {', '.join(adoption)}")
|
|
104
|
+
|
|
105
|
+
sc = notes.get("scorecard")
|
|
106
|
+
if sc and sc.get("score") is not None:
|
|
107
|
+
weak = sorted((v, k) for k, v in sc["checks"].items() if v <= 3)[:4]
|
|
108
|
+
weak_text = f"; weak spots: {', '.join(f'{k} {v}/10' for v, k in weak)}" if weak else ""
|
|
109
|
+
lines.append(f"- **Security practices (OpenSSF Scorecard):** {sc['score']}/10{weak_text}")
|
|
110
|
+
adv = (pkg or {}).get("advisories")
|
|
111
|
+
if adv is not None:
|
|
112
|
+
if adv["count"]:
|
|
113
|
+
lines.append(f"- **Known vulnerabilities in latest version ({adv['version']}):** "
|
|
114
|
+
f"{adv['count']} ({', '.join(adv['ids'])})")
|
|
115
|
+
else:
|
|
116
|
+
lines.append(f"- **Known vulnerabilities in latest version ({adv['version']}):** none listed in OSV")
|
|
117
|
+
|
|
118
|
+
hn = notes.get("hacker_news")
|
|
119
|
+
if hn and hn["stories"]:
|
|
120
|
+
top = "; ".join(f"[{s['title']}]({s['url']}) ({s['points']} points, {s['comments']} comments, {s['year']})"
|
|
121
|
+
for s in hn["top"])
|
|
122
|
+
lines.append(f"- **Hacker News:** {hn['stories']} stories link to it. Top: {top}")
|
|
123
|
+
elif hn is not None:
|
|
124
|
+
lines.append("- **Hacker News:** no stories link to it")
|
|
125
|
+
|
|
126
|
+
if readme and readme["mentions_needing"]:
|
|
127
|
+
lines.append(f"- **README mentions (likely setup needs):** {', '.join(readme['mentions_needing'])}")
|
|
128
|
+
if readme and readme["maturity_flags"]:
|
|
129
|
+
lines.append("- **Maturity flags in README:**")
|
|
130
|
+
lines += [f" - \"{m}\"" for m in readme["maturity_flags"]]
|
|
131
|
+
for w in h["warnings"]:
|
|
132
|
+
lines.append(f"- **Watch out:** {w}")
|
|
133
|
+
if notes.get("unavailable"):
|
|
134
|
+
lines.append(f"- _Couldn't check: {', '.join(notes['unavailable'])}_")
|
|
135
|
+
lines.append("")
|
|
136
|
+
return lines
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def format_component(comp: dict, number: int | None = None) -> list[str]:
|
|
140
|
+
lines = [f"## {number}. {comp['name']}" if number else f"## {comp['name']}"]
|
|
141
|
+
if comp.get("why"):
|
|
142
|
+
lines.append(f"_Why: {comp['why']}_")
|
|
143
|
+
lines.append("")
|
|
144
|
+
if comp.get("error"):
|
|
145
|
+
lines += [f"Not searched: {comp['error']}", ""]
|
|
146
|
+
return lines
|
|
147
|
+
if comp["top"]:
|
|
148
|
+
lines += format_repo_table(comp["top"])
|
|
149
|
+
else:
|
|
150
|
+
lines.append(f"No free, maintained tool found (searched GitHub for `{comp.get('query', '')}`). "
|
|
151
|
+
"Try describing the need in different words.")
|
|
152
|
+
if comp.get("rejected"):
|
|
153
|
+
skipped = ", ".join(f"{r['full_name']} ({r['health']['rejected_because'][0]})" for r in comp["rejected"][:5])
|
|
154
|
+
lines += ["", f"Skipped: {skipped}"]
|
|
155
|
+
for note in comp.get("notes", []):
|
|
156
|
+
lines += ["", f"Note: {note}"]
|
|
157
|
+
lines.append("")
|
|
158
|
+
researched = [r for r in comp["top"] if r.get("research")]
|
|
159
|
+
if researched:
|
|
160
|
+
for r in researched:
|
|
161
|
+
lines += format_research(r)
|
|
162
|
+
else:
|
|
163
|
+
warnings = [(r["full_name"], w) for r in comp["top"] for w in r["health"]["warnings"]]
|
|
164
|
+
if warnings:
|
|
165
|
+
lines += ["Watch out:"] + [f"- {name}: {w}" for name, w in warnings] + [""]
|
|
166
|
+
return lines
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def format_report(result: dict) -> str:
|
|
170
|
+
comps = result["components"]
|
|
171
|
+
checked = sum(c.get("considered", 0) for c in comps)
|
|
172
|
+
skipped = sum(len(c.get("rejected", [])) for c in comps)
|
|
173
|
+
lang = result.get("language")
|
|
174
|
+
lines = [
|
|
175
|
+
f"# Free tool stack for: {result['idea']}" if result.get("idea") else "# Free tool stack",
|
|
176
|
+
"",
|
|
177
|
+
f"{len(comps)} need{'s' if len(comps) != 1 else ''} · {checked} repos checked · "
|
|
178
|
+
f"{skipped} skipped as archived, stale, not free, or not a tool"
|
|
179
|
+
+ (f" · language: {lang} (applied to code libraries only)" if lang else ""),
|
|
180
|
+
"",
|
|
181
|
+
"Listed tools are open source (or open core, flagged), not archived, and had code changes in the "
|
|
182
|
+
"last 2 years. Score (0-100) = popularity + recent activity + how free the license is.",
|
|
183
|
+
"",
|
|
184
|
+
]
|
|
185
|
+
for i, comp in enumerate(comps, 1):
|
|
186
|
+
lines += format_component(comp, i if len(comps) > 1 else None)
|
|
187
|
+
lines += [
|
|
188
|
+
"---",
|
|
189
|
+
AI_NOTE,
|
|
190
|
+
"",
|
|
191
|
+
f"_Generated {result.get('generated_at', '')} by Stack Scout from public data "
|
|
192
|
+
"(GitHub, deps.dev, OSV, npm/PyPI/crates.io, Hacker News)._",
|
|
193
|
+
]
|
|
194
|
+
return "\n".join(lines)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
if __name__ == "__main__":
|
|
198
|
+
if len(sys.argv) != 2:
|
|
199
|
+
sys.exit("usage: python -m stack_scout_mcp.tools.format_report result.json")
|
|
200
|
+
sys.stdout.reconfigure(encoding="utf-8")
|
|
201
|
+
print(format_report(json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))))
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
"""Search GitHub for repositories that provide a building block (auth, payments, ...).
|
|
2
|
+
|
|
3
|
+
Uses the free GitHub REST API. Works without a token (10 searches/min);
|
|
4
|
+
set GITHUB_TOKEN in .env to raise that to 30/min.
|
|
5
|
+
|
|
6
|
+
CLI:
|
|
7
|
+
python -m stack_scout_mcp.tools.github_search "headless cms" --language TypeScript --limit 10
|
|
8
|
+
python -m stack_scout_mcp.tools.github_search --repo medusajs/medusa
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import argparse
|
|
13
|
+
import json
|
|
14
|
+
import os
|
|
15
|
+
import sys
|
|
16
|
+
import urllib.parse
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
|
|
19
|
+
from ._common import http_get, load_env
|
|
20
|
+
|
|
21
|
+
API = "https://api.github.com"
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _headers() -> dict:
|
|
25
|
+
load_env()
|
|
26
|
+
headers = {"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28"}
|
|
27
|
+
token = os.environ.get("GITHUB_TOKEN", "").strip()
|
|
28
|
+
if token:
|
|
29
|
+
headers["Authorization"] = f"Bearer {token}"
|
|
30
|
+
return headers
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def slim_repo(r: dict) -> dict:
|
|
34
|
+
"""Keep only the fields the rest of the pipeline uses."""
|
|
35
|
+
lic = r.get("license") or {}
|
|
36
|
+
return {
|
|
37
|
+
"full_name": r["full_name"],
|
|
38
|
+
"url": r["html_url"],
|
|
39
|
+
"description": (r.get("description") or "").strip(),
|
|
40
|
+
"stars": r.get("stargazers_count", 0),
|
|
41
|
+
"forks": r.get("forks_count", 0),
|
|
42
|
+
"open_issues": r.get("open_issues_count", 0),
|
|
43
|
+
"language": r.get("language"),
|
|
44
|
+
"license": lic.get("spdx_id") or None,
|
|
45
|
+
"license_name": lic.get("name"),
|
|
46
|
+
"pushed_at": r.get("pushed_at"),
|
|
47
|
+
"archived": bool(r.get("archived")),
|
|
48
|
+
"fork": bool(r.get("fork")),
|
|
49
|
+
"topics": r.get("topics") or [],
|
|
50
|
+
"homepage": r.get("homepage") or None,
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def search_repos(query: str, language: str | None = None, min_stars: int = 50, limit: int = 15) -> list[dict]:
|
|
55
|
+
"""Return up to `limit` repos for `query`, in GitHub's best-match order."""
|
|
56
|
+
parts = [query.strip(), "archived:false", "fork:false", f"stars:>={min_stars}"]
|
|
57
|
+
if language:
|
|
58
|
+
parts.append(f'language:"{language}"')
|
|
59
|
+
params = urllib.parse.urlencode({"q": " ".join(parts), "per_page": max(1, min(limit, 50))})
|
|
60
|
+
data = json.loads(http_get(f"{API}/search/repositories?{params}", headers=_headers()))
|
|
61
|
+
return [slim_repo(r) for r in data.get("items", [])]
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def get_repo(full_name: str) -> dict:
|
|
65
|
+
"""Fetch one repo by 'owner/name' (also accepts a full github.com URL)."""
|
|
66
|
+
full_name = full_name.strip().removeprefix("https://").removeprefix("http://")
|
|
67
|
+
full_name = full_name.removeprefix("github.com/").strip("/")
|
|
68
|
+
owner, _, name = full_name.partition("/")
|
|
69
|
+
name = name.split("/")[0].removesuffix(".git")
|
|
70
|
+
if not owner or not name:
|
|
71
|
+
raise ValueError(f"Expected 'owner/repo', got {full_name!r}")
|
|
72
|
+
data = json.loads(http_get(f"{API}/repos/{owner}/{name}", headers=_headers()))
|
|
73
|
+
return slim_repo(data)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def main() -> None:
|
|
77
|
+
p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
78
|
+
p.add_argument("query", nargs="?", help="What to search for, e.g. 'authentication'")
|
|
79
|
+
p.add_argument("--repo", help="Fetch a single repo instead, e.g. owner/name")
|
|
80
|
+
p.add_argument("--language", help="Only repos in this language, e.g. TypeScript")
|
|
81
|
+
p.add_argument("--min-stars", type=int, default=50)
|
|
82
|
+
p.add_argument("--limit", type=int, default=15)
|
|
83
|
+
args = p.parse_args()
|
|
84
|
+
if args.repo:
|
|
85
|
+
result = get_repo(args.repo)
|
|
86
|
+
elif args.query:
|
|
87
|
+
result = search_repos(args.query, args.language, args.min_stars, args.limit)
|
|
88
|
+
else:
|
|
89
|
+
p.error("give a query or --repo")
|
|
90
|
+
print(json.dumps(result, indent=2))
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
if __name__ == "__main__":
|
|
94
|
+
main()
|