Repository navigation
Expand file tree
/
Copy pathserver.py
More file actions
1813 lines (1715 loc) · 103 KB
/
Copy pathserver.py
File metadata and controls
1813 lines (1715 loc) · 103 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
from __future__ import annotations
import asyncio
import json
import logging
import re
from datetime import datetime, timedelta, timezone
from typing import Any
logger = logging.getLogger("codesearch")
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import CallToolResult, ListToolsResult, TextContent, Tool
from config import GH_TOKEN, SOFA_KEY, LI_KEY, close_http_client, get_http_client, api_error
import llm
from embed import _embed, _dedup_rank, _hybrid_rank
from code_expand import expand_code_query
from context7 import context7_resolve, search_llms_txt, context7_add_repo
from github_api import search_github
from deepwiki import deepwiki_fetch, deepwiki_ask
from codewiki import codewiki_fetch_repo, codewiki_search_repos, codewiki_ask_repo
from pkgseer import (
search as pkgseer_search,
code_files as pkgseer_code_files,
code_read as pkgseer_code_read,
code_grep as pkgseer_code_grep,
pkg_deps as pkgseer_pkg_deps,
jsdelivr_list_files,
jsdelivr_read_file,
)
from analyze import analyze_repo
from searchcode import (
analyze as searchcode_analyze,
search as searchcode_search,
file_tree as searchcode_file_tree,
get_file as searchcode_get_file,
findings as searchcode_findings,
)
from stack_exchange import (search_so, so_similar, so_tags_info, so_tags_wikis,
get_questions_by_ids, search_users, search_tags, get_question_comments,
get_answers_by_ids, get_questions_by_sort, get_users_by_ids)
from sofa import search_sofa
from hackernews import search_hn, hn_get_item, hn_firebase_stories, hn_get_user
from libraries_io import (search_libraries_io, libraries_io_search, get_versions,
get_dependencies, get_dependents, get_github_repo, get_github_dependencies,
li_list_platforms, li_list_licenses, li_keyword_projects)
from oss_index import (scan_vulnerabilities, get_vulnerability_detail, get_component_latest_version,
analyze_license)
from ghsa import ghsa_search as _ghsa_search
from nvd import attach_nvd as _attach_nvd
from grep_mcp import grep_mcp_search
from sourcegraph import search_sourcegraph
from scorecard import scorecard_score
from readthedocs import (search_readthedocs, readthedocs_project_info, readthedocs_versions,
readthedocs_translations, readthedocs_subprojects, readthedocs_builds)
from registries import (search_package, npm_search, crates_search, get_npm_versions,
get_npm_time, get_crates_versions,
get_pypi_version, get_pypi_versions,
npm_get_version, crates_get_version, crates_get_readme, crates_get_summary)
from devdocs import (devdocs_list_docs, devdocs_fetch, devdocs_fetch_content,
devdocs_search, devdocs_meta, devdocs_toc)
from semantic_scholar import (search_papers, get_paper_details,
get_papers_batch, get_paper_citations, get_paper_references,
get_paper_recommendations, search_authors, get_author_papers,
autocomplete_papers, s2_author_by_id, s2_bulk_search,
s2_recommendations_with_negatives)
from core_api import search_core_works, CORE_API_AVAILABLE
from depsdev import get_resolved_dependencies, get_package_info as get_depsdev_package_info, get_advisory, query_by_hash
from reranker import rerank as _rerank, killswitch_active
from tavily_search import tavily_search
from enrich import enrich_results
from pkg_utils import (get_pkg_changelog, get_pkg_upgrade_review,
list_package_files, read_package_file, resolve_package)
from openalex import search_openalex, search_openalex_authors, search_openalex_topics, search_openalex_institutions, search_openalex_sources
INSTRUCTIONS = """# CodeSearch MCP
Public-data code/package/docs/paper search server. Searches the public internet
(packages, docs, papers, public repos). NOT a local repo indexer — for your own
working tree use ripgrep/ast-grep/serena MCPs instead.
## When to use what
- **search_all** (flagship): broad multi-source discovery (18 lanes) with embedding
dedup + hybrid rank + rerank + optional synthesis. Start here for open-ended
questions.
- **analyze**: deep single-repo understanding.
- GitHub data: search_all includes a github code lane; for issue/PR/repo queries
prefer the authenticated `gh` CLI (`gh issue view`, `gh pr view --diff`,
`gh search code/repos/issues`). gh also does mutations.
- **searchcode**: per-repo code quality analysis. **code_search/code_files/code_read**
for per-package source browsing (PkgSeer) + global public-code search (Sourcegraph,
keyless).
- **docs**: API/library docs (ReadTheDocs -> DevDocs -> llms.txt -> Context7, Context7
last to stretch its 1000/mo quota). **wiki**: repo architecture Q&A.
- **papers**: academic research (Semantic Scholar -> arXiv -> OpenAlex -> CORE).
**so_search**: community Q&A. **hn**: tech discussion.
- **pkg**: composite package info (Libraries.io + Sonatype/OSV vulns + Scorecard).
**search_package**: fast single-registry lookups. **search_libraries**: dependency
metadata. **vulns**: vulnerability scanning (Sonatype Guide + keyless OSV.dev
fallback; GHSA enrichment; CISA KEV). **enrich**: fetch+rerank results you have.
- **ping**: connectivity check.
Tool list (17): ping, wiki, search_all, search_package, so_search, hn,
search_libraries, vulns, docs, papers, searchcode, code_search, code_files,
code_read, pkg, enrich, analyze.
## Model path (synthesis)
Free-first: local reflection/beam:free route is tried first, Groq (openai/gpt-oss-120b)
is the fallback. Synthesis works without GROQ_API_KEYS via the local route; with no
endpoint configured it is skipped and raw results are returned. `model_calls` in the
response reports what ran. Set synthesize=false for raw results only.
## Pipeline (search_all)
search_all -> multi-source -> dedup -> hybrid rank -> reranker -> synthesis (free-first).
## Params
- `language`: always pass known languages
- `tags`: SO queries — scope to ecosystem (python, react, rust)
- `owner`/`repo`: GitHub-specific queries
- `accepted=true`: so_search for resolved/verified answers
- `fields_of_study`: papers domain filter (Computer Science, Physics, etc.)
- `min_points`/`min_comments`: HN quality floor
- `synthesize=true`: get a summarized answer (free-first; no-op only when no endpoint
is configured). default on for search_all; off for searchcode/code tools.
"""
# Query->tag/platform/domain detection helpers for search_all precision
_SE_TAGS = re.compile(r"(?i)\b(react|typescript|javascript|python|rust|golang?|docker|kubernetes|postgresql|mysql|sql|aws|git|node\.?js|angular|vue|django|flask|fastapi|spring|jvm|scala|kotlin|swift|ruby|rails|php|laravel|lua|c\+\+|csharp|dotnet|unity|unreal|tensorflow|pytorch|jax|linux|bash|shell|nix|nixos|ansible|terraform|graphql|rest|grpc|websocket|redis|mongodb|sqlite|svelte|next\.?js|nuxt|deno|bun)\b")
_LI_PLATFORM = re.compile(r"(?i)\b(python|javascript|typescript|rust|golang?|java|ruby|php|swift|kotlin|lua|c\+\+|csharp|dart|elixir|haskell|scala|perl|r)\b")
_LI_PLATFORM_MAP = {"python":"pypi","javascript":"npm","typescript":"npm","rust":"cargo","golang":"go","java":"maven","ruby":"rubygems","php":"packagist","swift":"swift","kotlin":"maven","csharp":"nuget","dart":"pub","elixir":"hex","haskell":"hackage","scala":"maven","perl":"cpan"}
def safe_int(v, default=0):
try:
return int(v)
except (TypeError, ValueError):
return default
def safe_float(v, default=0.0):
try:
return float(v)
except (TypeError, ValueError):
return default
async def handle_list_tools(ctx, params) -> ListToolsResult:
return ListToolsResult(tools=[
Tool(
name="ping",
description="Lightweight connectivity check — verifies internet and key API endpoints are reachable. Returns success=true only if at least one target is reachable (all_reachable reports whether every target was reachable). Use before expensive calls when connectivity is uncertain. No params needed. e.g. ping()",
input_schema={
"type": "object",
"properties": {},
},
),
Tool(
name="wiki",
description="Repo architecture and wiki via DeepWiki + CodeWiki. For single-repo queries use owner+repo; for multi-repo questions pass repos (array of owner/repo strings, max 10). e.g. wiki(owner='torvalds', repo='linux', question='How does the scheduler work?')",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["search", "fetch", "ask", "architecture"]},
"owner": {"type": "string"},
"repo": {"type": "string"},
"repos": {"type": "array", "items": {"type": "string"}, "description": "Array of owner/repo strings for multi-repo queries (DeepWiki ask supports up to 10)"},
"question": {"type": "string"},
"wiki_name": {"type": "string"},
"query": {"type": "string"},
"limit": {"type": "integer", "default": 5},
"offset": {"type": "integer", "default": 0},
},
"required": ["action"],
},
),
Tool(
name="search_all",
description="Unified search across 14+ sources with embedding dedup and reranking. Use for broad multi-source discovery; for surgical single-source work call so_search/hn/papers/code_search directly. e.g. search_all(query='rust async runtime', language='rust')",
input_schema={
"type": "object",
"properties": {
"query": {"type": "string"},
"library": {"type": "string"},
"version": {"type": "string"},
"owner": {"type": "string"},
"repo": {"type": "string"},
"language": {"type": "string"},
"count": {"type": "integer", "default": 5, "description": "Results per source (max 50). Default 5 keeps payload under budget; raise explicitly for depth."},
"fields_of_study": {"type": "string", "description": "S2 papers domain filter (default: all fields)"},
"so_sort": {"type": "string", "default": "votes", "description": "Stack Exchange sort: votes/activity/creation/relevance"},
"fromdate": {"type": "string", "description": "Stack Exchange results older than ISO date"},
"todate": {"type": "string", "description": "Stack Exchange results newer than ISO date"},
"synthesize": {"type": "boolean", "default": True, "description": "Summarize top results into a concise answer with citations (free-first local route, Groq fallback; no-op only when no endpoint is configured)"},
"compact": {"type": "boolean", "default": False, "description": "Compact mode: top-3 per lane, snippets <=300 chars, fewer sources (payload budget guard). Full capability remains reachable via explicit count/compact=false."},
},
"required": ["query"],
},
),
Tool(
name="search_package",
description="Raw single-registry package queries (npm/PyPI/crates + deps.dev). Use for fast version/dependency lookups on ONE registry. For composite intelligence (Libraries.io + Sonatype/OSV vulns + Scorecard), use `pkg` instead.",
input_schema={
"type": "object",
"properties": {
"name": {"type": "string"},
"registry": {"type": "string", "default": "auto"},
"action": {"type": "string", "enum": ["npm_versions","pypi_versions","crates_versions","npm_dist_tags","npm_get_version","pypi_get_version","crates_get_version","crates_get_readme","crates_summary","depsdev_dependencies","depsdev_info","depsdev_advisory","depsdev_query","npm_time","crates_downloads","crates_reverse_deps","crates_owners","crates_categories","crates_keywords","npm_search","crates_search"], "description": "list versions: npm_versions|pypi_versions|crates_versions; one version: npm_get_version|pypi_get_version|crates_get_version (version='latest' OK); npm_dist_tags; crates_get_readme|crates_summary; depsdev_dependencies|depsdev_info|depsdev_advisory|depsdev_query. Full metadata: use pkg."},
"version": {"type": "string", "description": "Package version (required for version-specific queries; 'latest' resolves to newest)"},
"advisory_id": {"type": "string", "description": "OSV advisory ID for depsdev_advisory"},
"hash_type": {"type": "string", "description": "Hash type for depsdev_query: SHA1, SHA256, etc"},
"hash_value": {"type": "string", "description": "Base64-encoded hash value for depsdev_query"},
},
"required": ["name"],
},
),
Tool(
name="so_search",
description="Stack Overflow: Stack Exchange API (free, 300 req/day, resolved/accepted answers with score/tags) or SOFA (Stack Overflow for Agents, beta, agent-contributed content with trust scores, requires SOFA_KEY env). Use stackexchange for authoritative resolved answers, sofa for fresher agent-contributed content. e.g. so_search(query='python async', tags='python', accepted=true)",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["stackexchange", "sofa", "questions_by_ids", "search_users", "search_tags", "question_comments", "questions", "answers", "users"], "default": "stackexchange", "description": "stackexchange=official API (free, 300 req/day, resolved answers, score/tags/views/activity). sofa=Stack Overflow for Agents (beta, agent-contributed, trust scores, needs SOFA_KEY). questions_by_ids/search_users/search_tags/question_comments/questions/answers/users are Stack Exchange sub-actions"},
"query": {"type": "string"},
"count": {"type": "integer", "default": 5},
"tags": {"type": "string"},
"accepted": {"type": "boolean"},
"closed": {"type": "boolean"},
"sort": {"type": "string", "default": "relevance"},
"type": {"type": "string", "default": "search", "enum": ["search", "excerpts", "faq", "answers", "similar", "tags_info", "tags_wikis"]},
"site": {"type": "string", "default": "stackoverflow"},
"question_id": {"type": "integer"},
"ids": {"type": "string", "description": "Comma-separated IDs for questions_by_ids / answers_by_ids / users_by_ids"},
"page": {"type": "integer", "default": 1, "description": "Page number for pagination"},
"fromdate": {"type": "string", "description": "Unix timestamp or date string for earliest creation date"},
"todate": {"type": "string", "description": "Unix timestamp or date string for latest creation date"},
"views": {"type": "integer", "default": 0, "description": "Minimum view count"},
"answers": {"type": "integer", "default": 0, "description": "Minimum answer count"},
"content_type": {"type": "string", "default": "question", "description": "SOFA only: question|til|blueprint|playbook"},
"post_id": {"type": "string", "description": "SOFA only: get post by ID instead of searching"},
"steering": {"type": "string", "description": "SOFA only: curation steering parameter"},
},
},
),
Tool(
name="hn",
description="Hacker News: search, item detail, user profile, or story lists (top/new/best/ask/show). Use for tech-community discussion and sentiment; for resolved Q&A use so_search. e.g. hn(query='rust', tags='story', min_points=50)",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["search","item","stories","user"]},
"query": {"type": "string"},
"count": {"type": "integer", "default": 5},
"sort_by_date": {"type": "boolean"},
"tags": {"type": "string", "default": "story", "description": "story|comment|poll|front_page|ask_hn|show_hn"},
"min_points": {"type": "integer", "default": 0},
"min_comments": {"type": "integer", "default": 0},
"item_id": {"type": "integer"},
"firebase_type": {"type": "string"},
"username": {"type": "string"},
},
"required": ["action"],
},
),
Tool(
name="search_libraries",
description="Libraries.io dependency metadata and source rank. Use to compare dependency candidates or find the repo behind a package; for registry versions/vulns use search_package/pkg/vulns. e.g. search_libraries(name='lodash', platform='npm')",
input_schema={
"type": "object",
"properties": {
"name": {"type": "string"},
"platform": {"type": "string", "default": ""},
"query": {"type": "string"},
"sort": {"type": "string"},
"languages": {"type": "string"},
"licenses": {"type": "string"},
"keywords": {"type": "string"},
"action": {"type": "string", "enum": ["versions","dependencies","dependents","github_repo","github_dependencies","platforms","licenses","keywords"], "description": "versions|dependencies|dependents|github_repo|github_dependencies|platforms|licenses|keywords (omit for project search)"},
"version": {"type": "string"},
"owner": {"type": "string"},
"repo": {"type": "string"},
"keyword": {"type": "string", "description": "Keyword for keywords action"},
"count": {"type": "integer", "default": 10},
},
},
),
Tool(
name="vulns",
description="Sonatype Guide + OSV.dev fallback: scan packages, vulnerability details, latest version, or license analysis by PURL. scan needs platform+name+version (or coordinates) — on Sonatype 401/429/quota errors it falls back to keyless OSV.dev automatically. detail accepts Sonatype ids, GHSA-* (GitHub Advisory enrichment), or CVE-* ids. latest_version/license need purl. e.g. vulns(action='scan', name='lodash', version='4.17.20')",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["scan", "detail", "latest_version", "license"]},
"platform": {"type": "string"},
"name": {"type": "string"},
"version": {"type": "string"},
"coordinates": {"type": "string"},
"vuln_id": {"type": "string"},
"purl": {"type": "string"},
},
"required": [],
},
),
Tool(
name="docs",
description="Documentation operations. Default action runs smart fallback (ReadTheDocs→DevDocs→llms.txt→Context7, quota-free sources first). After finding docs, use fetch(url) to read full pages or devdocs_fetch_content for structured content. e.g. docs(query='authentication', library='express')",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["search", "devdocs_search", "devdocs_fetch", "devdocs_fetch_content", "devdocs_list", "devdocs_meta", "devdocs_toc", "rtd_search", "rtd_info", "rtd_versions", "rtd_builds", "rtd_translations", "rtd_subprojects", "context7_add_repo"], "default": "search"},
"query": {"type": "string"},
"library": {"type": "string"},
"library_id": {"type": "string", "description": "Context7 library ID (skip search)"},
"version": {"type": "string"},
"fast": {"type": "boolean"},
"slug": {"type": "string"},
"path": {"type": "string"},
"project": {"type": "string"},
"provider": {"type": "string", "description": "Git provider for context7_add_repo (github, gitlab)"},
"repo_url": {"type": "string", "description": "Repository URL for context7_add_repo"},
},
},
),
Tool(
name="papers",
description="Academic papers from Semantic Scholar, CORE API, and arXiv. Prefer action=search for topic queries (multi-source S2→arXiv→OpenAlex→CORE fallback); arxiv_search is single-source and rate-limited. e.g. papers(query='transformer attention', fields_of_study='Computer Science')",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["search", "details", "batch", "citations", "references", "recommendations", "author_search", "author_papers", "autocomplete", "core_search", "author_by_id", "bulk_search", "recommendations_negatives", "arxiv_search"]},
"query": {"type": "string"},
"paper_id": {"type": "string"},
"paper_ids": {"type": "string", "description": "Comma-separated paper IDs for batch action"},
"author_id": {"type": "string"},
"count": {"type": "integer", "default": 10},
"offset": {"type": "integer", "default": 0, "description": "Result offset for pagination (search and core_search actions)"},
"year": {"type": "string"},
"fields_of_study": {"type": "string"},
"open_access": {"type": "boolean"},
"positive_ids": {"type": "string", "description": "Comma-separated positive paper IDs for recommendations_negatives"},
"negative_ids": {"type": "string", "description": "Comma-separated negative paper IDs for recommendations_negatives"},
},
"required": ["action"],
},
),
Tool(
name="searchcode",
description="Per-repo code intelligence via SearchCode (free, no auth). Use analyze for instant repo overview (languages, complexity, tech stack, credentials), search for searching code within a repo, findings for code quality issues, file_tree to list files, or get_file to read a file. No rate limits. e.g. searchcode(action='analyze', repository='https://github.com/expressjs/express')",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["analyze", "search", "findings", "file_tree", "get_file"], "description": "analyze=repo overview, search=search code, findings=quality issues, file_tree=list files, get_file=read file"},
"repository": {"type": "string", "description": "Git URL or owner/repo — REQUIRED for every searchcode action (e.g. https://github.com/expressjs/express)"},
"query": {"type": "string", "description": "Search query (for search action)"},
"path": {"type": "string", "description": "Subdirectory path filter (for analyze/findings/file_tree)"},
"language": {"type": "string", "description": "Language filter (for analyze action)"},
"detail_level": {"type": "string", "enum": ["summary", "full"], "default": "summary", "description": "Response verbosity (for analyze action)"},
"symbol_name": {"type": "string", "description": "Function/class name to extract (for get_file action)"},
"case_sensitive": {"type": "boolean", "default": False, "description": "Case-sensitive search (for search action)"},
"context_lines": {"type": "integer", "default": 2, "description": "Context lines around matches (for search action)"},
"max_results": {"type": "integer", "default": 10, "description": "Max results (for search/findings)"},
"severity": {"type": "string", "enum": ["error", "warning", "info"], "description": "Filter by severity (for findings action)"},
"category": {"type": "string", "enum": ["security", "deprecated", "safety", "correctness", "maintainability", "accessibility", "modernization", "performance", "concurrency"], "description": "Filter findings by category (for findings action)"},
"start_line": {"type": "integer", "default": 1, "description": "Start line (for get_file without symbol_name)"},
"end_line": {"type": "integer", "description": "End line (for get_file without symbol_name)"},
},
"required": ["action"],
},
),
Tool(
name="code_search",
description="Search code, docs, and symbols across indexed dependencies and public repositories. Package scope (npm:express, pypi:requests) via PkgSeer; global public-code search via Sourcegraph (keyless). Supports qualifiers like kind:, category:, lang:. e.g. code_search(query='handleAuth', target='npm:express')",
input_schema={
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query supporting implicit AND, OR, parens, -exclude, and qualifiers (kind:, lang:, path:)"},
"target": {"type": "string", "description": "Package scope: registry:name[@version] (npm:express, pypi:requests, crates:serde). PkgSeer indexes npm/pypi/crates only. Omit target for global public-repo search via Sourcegraph (keyless). For single GitHub repos use `searchcode` (repository=URL) or `analyze`."},
"source": {"type": "string", "enum": ["docs", "code", "symbol"], "description": "Restrict results to a specific source type"},
"lang": {"type": "string", "description": "Programming language filter"},
"limit": {"type": "integer", "default": 10, "description": "Max results (1-100)"},
},
"required": ["query"],
},
),
Tool(
name="code_files",
description="List files in an indexed dependency by package-scoped path (e.g. npm:express/src/). PkgSeer + jsDelivr; indexes npm/pypi/crates ONLY (github: specs rejected). e.g. code_files(spec='npm:express')",
input_schema={
"type": "object",
"properties": {
"spec": {"type": "string", "description": "Package spec: registry:name[@version] (e.g. npm:express, pypi:requests)"},
"path_prefix": {"type": "string", "description": "Optional path prefix filter (e.g. src/)"},
},
"required": ["spec"],
},
),
Tool(
name="code_read",
description="Read a file from an indexed dependency by package-scoped path. PkgSeer + jsDelivr; indexes npm/pypi/crates ONLY (github: specs rejected). e.g. code_read(spec='npm:express', path='src/index.js')",
input_schema={
"type": "object",
"properties": {
"spec": {"type": "string", "description": "Package spec: registry:name[@version] (e.g. npm:express)"},
"path": {"type": "string", "description": "File path within the package (e.g. src/index.js)"},
},
"required": ["spec", "path"],
},
),
Tool(
name="pkg",
description="Package intelligence: info (composite metadata — Libraries.io + Sonatype + PkgSeer), changelog (release notes), upgrade_review (vulns+changelog+deps diff between versions), files (list source files), read (read a source file). For raw single-source registry queries (npm versions, crates categories), use `search_package` instead. e.g. pkg(name='express', action='info')",
input_schema={
"type": "object",
"properties": {
"action": {"type": "string", "enum": ["info", "changelog", "upgrade_review", "files", "read"], "default": "info"},
"name": {"type": "string"},
"registry": {"type": "string", "default": "auto"},
"version": {"type": "string", "description": "Package version (default: latest)"},
"current_version": {"type": "string", "description": "Current version for upgrade_review"},
"target_version": {"type": "string", "description": "Target version for upgrade_review"},
"from_version": {"type": "string", "description": "Start of version range for changelog (optional)"},
"to_version": {"type": "string", "description": "End of version range for changelog (optional)"},
"path": {"type": "string", "description": "File path filter (files) or exact path (read)"},
"count": {"type": "integer", "default": 10, "description": "Max changelog entries"},
},
"required": ["name"],
},
),
Tool(
name="enrich",
description="Fetch full content for a list of search results, deduplicate, and rerank by relevance. Give it results from any search tool plus the original query. e.g. enrich(query='rust async', results=[{'url':'...','title':'...'}])",
input_schema={
"type": "object",
"properties": {
"query": {"type": "string"},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {"type": "string", "description": "Page URL to fetch content from"},
"title": {"type": "string", "description": "Page title"},
"text": {"type": "string", "description": "Page text or snippet"},
"snippet": {"type": "string", "description": "Search snippet if full text not available"},
"source": {"type": "string", "description": "Engine or source name (e.g. github, hn)"},
},
},
"description": "List of result objects to enrich (url, title, text/snippet, source)",
},
"top_k": {"type": "integer", "default": 20, "description": "Max enriched results to return"},
"max_fetch_size": {"type": "integer", "default": 50, "description": "Max results to fetch content for"},
"max_urls": {"type": "integer", "default": 5, "description": "Cap on number of URLs fetched (payload budget guard)"},
"max_chars": {"type": "integer", "default": 4000, "description": "Per-URL content char cap; longer content is truncated and flagged"},
"include_html": {"type": "boolean", "default": False, "description": "Include raw HTML in content (default strips to text)"},
},
"required": ["query", "results"],
},
),
Tool(
name="analyze",
description="Deep repo analysis: parallel-fetch GitHub metadata + SearchCode code quality + DeepWiki architecture + CodeWiki sections in one call. Start here for unfamiliar repos before surgical wiki/searchcode calls. Accepts GitHub URLs or owner/repo strings. May take 10-15s (parallel API calls). e.g. analyze(repository='sst/opencode')",
input_schema={
"type": "object",
"properties": {
"repository": {"type": "string", "description": "GitHub repo: URL (https://github.com/owner/repo) or owner/repo string"},
},
"required": ["repository"],
},
),
])
def _to_year(v):
try:
return int(str(v)[:4])
except (ValueError, TypeError):
return None
def _norm_arxiv(p: dict) -> dict:
pid = p.get("paper_id", "")
return {
"paperId": f"arXiv:{pid}" if pid else "", "title": p.get("title", ""),
"year": _to_year(p.get("published", "")), "abstract": p.get("summary", ""),
"citationCount": 0, "url": f"https://arxiv.org/abs/{pid}" if pid else "",
"venue": ", ".join(p.get("categories", [])), "publicationDate": (p.get("published", "") or "")[:10],
"authors": p.get("authors", []), "externalIds": {"ArXiv": pid} if pid else {},
"tldr": "", "isOpenAccess": True, "openAccessPdf": p.get("pdf_url", "") or None,
"s2FieldsOfStudy": [], "publicationTypes": [], "referenceCount": 0,
"influentialCitationCount": 0, "source": "arxiv",
}
def _norm_openalex(w: dict) -> dict:
url = w.get("url", "")
return {
"paperId": url, "title": w.get("title", ""),
"year": _to_year(w.get("year")), "abstract": w.get("snippet", ""),
"citationCount": w.get("citations", 0), "url": w.get("doi", "") or url,
"venue": "", "publicationDate": "", "authors": w.get("authors", []),
"externalIds": {"DOI": w["doi"]} if w.get("doi") else {}, "tldr": "",
"isOpenAccess": False, "openAccessPdf": None, "s2FieldsOfStudy": [],
"publicationTypes": [w["type"]] if w.get("type") else [], "referenceCount": 0,
"influentialCitationCount": 0, "source": "openalex",
}
def _norm_core(w: dict) -> dict:
doi = w.get("doi", "")
url = w.get("downloadUrl", "") or (f"https://doi.org/{doi}" if doi else "")
return {
"paperId": f"CORE:{w['id']}" if w.get("id", "") else "", "title": w.get("title", ""),
"year": _to_year(w.get("year")), "abstract": w.get("abstract", ""),
"citationCount": 0, "url": url, "venue": w.get("publisher", ""),
"publicationDate": "", "authors": w.get("authors", []),
"externalIds": {"DOI": doi} if doi else {}, "tldr": "",
"isOpenAccess": bool(w.get("downloadUrl")), "openAccessPdf": w.get("downloadUrl", "") or None,
"s2FieldsOfStudy": [], "publicationTypes": [], "referenceCount": 0,
"influentialCitationCount": 0, "source": "core",
}
async def _arxiv_search(query: str, count: int) -> dict:
"""Keyless arXiv search. Shared by the arxiv_search action and the search fallback chain."""
import xml.etree.ElementTree as ET
try:
c = get_http_client()
params = {"search_query": f"all:{query}", "max_results": count,
"sortBy": "relevance", "sortOrder": "descending"}
resp = await c.get("https://export.arxiv.org/api/query", params=params, timeout=15)
if resp.status_code == 429:
return {"success": False, "error": "arXiv rate-limited (HTTP 429) — wait ~30s and retry, or use action=search which falls back across S2/arXiv/OpenAlex/CORE"}
if resp.status_code == 200:
papers = []
root = ET.fromstring(resp.content)
ns = {"a": "http://www.w3.org/2005/Atom",
"arxiv": "http://arxiv.org/schemas/atom"}
for entry in root.findall("a:entry", ns):
pid = entry.find("a:id", ns)
title = entry.find("a:title", ns)
summary = entry.find("a:summary", ns)
published = entry.find("a:published", ns)
cats = [c.get("term", "") for c in entry.findall("arxiv:primary_category", ns)]
authors = [a.find("a:name", ns).text if a.find("a:name", ns) is not None else ""
for a in entry.findall("a:author", ns)]
pdf_link = ""
for link in entry.findall("a:link", ns):
if link.get("title") == "pdf":
pdf_link = link.get("href", "")
break
papers.append({
"paper_id": pid.text.strip().split("/")[-1] if pid is not None and pid.text else "",
"title": title.text.strip() if title is not None and title.text else "",
"summary": summary.text.strip()[:500] if summary is not None and summary.text else "",
"published": published.text.strip()[:10] if published is not None and published.text else "",
"authors": authors,
"categories": cats,
"pdf_url": pdf_link,
})
return {"success": True, "total": len(papers), "papers": papers}
return {"success": False, "error": api_error("arXiv returned", resp)}
except Exception as e:
return {"success": False, "error": str(e)}
async def _papers_search(query: str, limit: int, year: str = "", fields_of_study: str = "",
open_access: bool = False, offset: int = 0) -> dict:
"""papers action=search: S2 first, then arXiv -> OpenAlex -> CORE.
One source's outage (e.g. S2 429 with no API key) no longer fails the call."""
r = await search_papers(query, limit, year, fields_of_study, open_access, offset)
if r.get("success"):
r["source"] = "semantic_scholar"
return r
s2_error = r.get("error", "unknown")
errors = {"semantic_scholar": s2_error}
empty_ok: dict | None = None
ar = await _arxiv_search(query, min(limit, 50))
if ar.get("success"):
if ar.get("papers"):
papers = [_norm_arxiv(p) for p in ar["papers"][:limit]]
return {"success": True, "source": "arxiv", "s2_error": s2_error,
"results": papers, "total": ar.get("total", len(papers)), "offset": 0}
empty_ok = empty_ok or {"success": True, "source": "arxiv", "s2_error": s2_error,
"results": [], "total": 0, "offset": 0}
else:
errors["arxiv"] = ar.get("error", "unknown")
oa = await search_openalex(query, limit)
if oa.get("success"):
if oa.get("results"):
papers = [_norm_openalex(w) for w in oa["results"][:limit]]
return {"success": True, "source": "openalex", "s2_error": s2_error,
"results": papers, "total": oa.get("total", len(papers)), "offset": 0}
empty_ok = empty_ok or {"success": True, "source": "openalex", "s2_error": s2_error,
"results": [], "total": 0, "offset": 0}
else:
errors["openalex"] = oa.get("error", "unknown")
if CORE_API_AVAILABLE:
co = await search_core_works(query, limit)
if co.get("success"):
if co.get("results"):
papers = [_norm_core(w) for w in co["results"][:limit]]
return {"success": True, "source": "core", "s2_error": s2_error,
"results": papers, "total": co.get("totalHits", len(papers)), "offset": 0}
empty_ok = empty_ok or {"success": True, "source": "core", "s2_error": s2_error,
"results": [], "total": 0, "offset": 0}
else:
errors["core"] = co.get("error", "unknown")
else:
errors["core"] = "CORE_API_KEY not set"
if empty_ok is not None:
return empty_ok
return {"success": False, "error": "all paper sources failed", "errors": errors}
def _availability_status(result) -> str:
"""Classify one search_all lane result into a caller-visible status string.
Never collapse to a bare "failed": a lane that returned
{"success": false, "error": ...} must surface that reason, and an
exception that stringifies to "" must still name its type.
"""
if isinstance(result, BaseException):
if isinstance(result, asyncio.TimeoutError):
return "timed_out"
# include the message — bare type names hide root causes, and some
# exceptions (httpx read errors, asyncio cancellations) stringify to "".
_msg = str(result).strip()
return (f"error: {type(result).__name__}: {_msg}" if _msg
else f"error: {type(result).__name__} (no message)")
if isinstance(result, dict) and result.get("success"):
# A lane that answered successfully but contributed nothing is not
# productive — surface that instead of a bare "success".
_count = None
for _key in ("total", "total_raw", "total_chars", "count",
"results", "items", "papers", "hits", "matches"):
if _key in result:
_v = result.get(_key)
if isinstance(_v, list):
_count = len(_v)
elif isinstance(_v, (int, float)):
_count = int(_v)
break
if _count == 0:
return "success (0 results)"
return "success"
if isinstance(result, dict) and result.get("skipped"):
# Not applicable to this request (e.g. PkgSeer without a target).
# Reporting that as "failed" sends callers chasing a phantom bug.
_why = (result.get("summary") or "skipped").strip()
return _why if _why.startswith("skipped") else f"skipped: {_why}"
if isinstance(result, dict):
# Propagate the real reason (and any status/code the lane gives).
_err = (result.get("error") or result.get("message")
or result.get("reason") or "").strip()
_extra = ""
if result.get("status") is not None:
_extra += f" status={result.get('status')}"
if result.get("code") is not None:
_extra += f" code={result.get('code')}"
if _err:
_msg = f"{_err}{_extra}".strip()
return f"failed: {_msg[:160]}" if len(_msg) > 160 else f"failed: {_msg}"
return "failed (no error message)"
return "failed"
async def _run_synthesis(merged, query, arguments):
"""Run the optional synthesis step, mutating `merged` in place."""
PROMPT_VERSION = "codesearch-synthesis-2026-10-30.1"
merged.setdefault("synthesis", None)
want_synth = bool(arguments.get("synthesize", llm.endpoints() != []))
if not llm.endpoints() and bool(arguments.get("synthesize", False)):
merged["synthesis"] = ("synthesis skipped: no model endpoint configured "
"— returning raw results; set DISTILL_API_KEY/GROQ_API_KEYS or pass synthesize=false")
merged["synthesis_error"] = merged["synthesis"]
merged["finish_reason"] = None
merged["truncated"] = False
merged["sources"] = []
merged["prompt_version"] = PROMPT_VERSION
merged["sources_used"] = 0
merged["engine_answers_used"] = 0
merged["sources_dropped_by_pool_cap"] = 0
merged["sources_dropped_by_domain_cap"] = 0
merged["raw_available_via"] = "search_all(..., synthesize=false)"
merged["model_calls"] = llm.counts()
return
if merged.get("deduped_results") and want_synth:
try:
top = merged["deduped_results"][:8]
dropped_pool = max(0, len(merged["deduped_results"]) - len(top))
from collections import Counter
doms = Counter()
for x in top:
url = x.get("url", "") or ""
domain = url.split("/")[2] if "://" in url else (x.get("source", "") or "")
doms[domain] += 1
dropped_domain = sum(v - 2 for v in doms.values() if v > 2)
ctx = "\n\n".join(f"[{i+1}] (source: {x.get('source','?')}) {x.get('title','')}: {(x.get('text','') or x.get('snippet','') or '')[:1500]}"
for i, x in enumerate(top))
text, finish, err, _att = await llm.chat(
[{"role": "system", "content": "Answer concisely about code/libraries from sources. Use [N] citations like [1][2]."},
{"role": "user", "content": f"Query: {query}\n\nSources:\n{ctx}"}],
max_tokens=1024, attempts=2, timeout=15, kind="synthesis", temperature=0.0,
)
sources = [{"n": i + 1, "title": x.get("title", "") or x.get("url", ""),
"url": x.get("url", ""),
"kind": "page",
"engine": x.get("engine", "") or x.get("source", "")}
for i, x in enumerate(top)]
merged["sources"] = sources
merged["finish_reason"] = finish
merged["truncated"] = (finish == "length")
merged["prompt_version"] = PROMPT_VERSION
merged["sources_used"] = len(top)
# codesearch has no engine-answer lanes; the field exists so the
# payload matches websearch's shape.
merged["engine_answers_used"] = 0
merged["sources_dropped_by_pool_cap"] = dropped_pool
merged["sources_dropped_by_domain_cap"] = dropped_domain
merged["raw_available_via"] = "search_all(..., synthesize=false)"
merged["temperature"] = 0.0
merged["max_tokens"] = 1024
if text:
merged["synthesis"] = text
merged["synthesis_provider"] = llm.last_provider() or (llm.endpoints()[0]["provider"] if llm.endpoints() else "")
merged["synthesis_model"] = llm.last_model() or (llm.endpoints()[0]["model"] if llm.endpoints() else "")
elif err:
merged["synthesis_error"] = err
# No text and an error: there is no finish reason to report.
merged["finish_reason"] = None
merged["truncated"] = False
except Exception as e: # noqa: BLE001
logger.warning("synthesis failed: %s", e)
merged["synthesis_error"] = str(e)
merged["finish_reason"] = None
merged["truncated"] = False
merged["sources"] = merged.get("sources", [])
merged["prompt_version"] = PROMPT_VERSION
else:
merged.setdefault("sources", [])
merged.setdefault("finish_reason", None)
merged.setdefault("truncated", False)
merged["prompt_version"] = PROMPT_VERSION
merged.setdefault("sources_used", 0)
merged.setdefault("engine_answers_used", 0)
merged.setdefault("sources_dropped_by_pool_cap", 0)
merged.setdefault("sources_dropped_by_domain_cap", 0)
merged.setdefault("raw_available_via", "search_all(..., synthesize=false)")
merged["model_calls"] = llm.counts()
async def handle_call_tool(ctx, params) -> CallToolResult:
name = params.name
arguments = params.arguments or {}
if not isinstance(arguments, dict):
return CallToolResult(
content=[TextContent(type="text", text=json.dumps({"error": "arguments must be a dict"}))],
is_error=True,
)
def _res(data, ok=True):
return CallToolResult(
content=[TextContent(type="text", text=json.dumps(data, default=str))],
is_error=not ok,
)
try:
if name == "ping":
c = get_http_client()
results = {}
all_reachable = True
any_reachable = False
for target, url in [("cloudflare", "https://1.1.1.1"), ("google", "https://www.google.com"), ("github", "https://api.github.com")]:
try:
r = await c.get(url, timeout=5)
results[target] = {"reachable": True, "status": r.status_code, "ms": int(r.elapsed.total_seconds() * 1000) if hasattr(r, 'elapsed') else None}
any_reachable = True
except Exception as e:
results[target] = {"reachable": False, "error": str(e)[:60]}
all_reachable = False
# Honest: success reflects whether any target was reachable.
return _res({"success": any_reachable, "all_reachable": all_reachable,
"connectivity": results}, any_reachable)
elif name == "wiki":
action = str(arguments.get("action", ""))
if action == "search":
r = await codewiki_search_repos(
query=str(arguments.get("query", "")),
limit=int(arguments.get("limit", 5)),
offset=int(arguments.get("offset", 0)),
)
return _res(r, r.get("success", False))
elif action == "fetch":
r = await codewiki_fetch_repo(
owner=str(arguments.get("owner", "")),
repo=str(arguments.get("repo", "")),
)
return _res(r, r.get("success", False))
elif action == "ask":
owner = str(arguments.get("owner", ""))
repo = str(arguments.get("repo", ""))
question = str(arguments.get("question", ""))
repos = arguments.get("repos")
if isinstance(repos, list) and repos:
deep_repos = repos[:10]
fallback_repo = repos[0]
fallback_owner = ""
fallback_repo_name = ""
if "/" in fallback_repo:
parts = fallback_repo.split("/", 1)
fallback_owner, fallback_repo_name = parts[0], parts[1]
else:
fallback_owner, fallback_repo_name = owner, fallback_repo
else:
deep_repos = None
fallback_owner, fallback_repo_name = owner, repo
try:
r = await asyncio.wait_for(deepwiki_ask(owner=owner, repo=repo, question=question, repos=deep_repos), timeout=60)
except asyncio.TimeoutError:
logger.warning("DeepWiki timeout for %s/%s", owner, repo)
r = {"success": False, "error": "DeepWiki timeout"}
else:
if r.get("success"):
r = dict(r)
r["answered_by"] = "deepwiki"
r["fallback"] = False
return _res(r)
r2 = await codewiki_ask_repo(fallback_owner, fallback_repo_name, question)
if isinstance(r2, dict):
r2 = dict(r2)
r2["answered_by"] = "codewiki"
r2["fallback"] = True
return _res(r2, r2.get("success", False) if isinstance(r2, dict) else False)
elif action == "architecture":
r = await deepwiki_fetch(
owner=str(arguments.get("owner", "")),
repo=str(arguments.get("repo", "")),
wiki_name=str(arguments.get("wiki_name", "")),
)
return _res(r, r.get("success", False))
else:
return _res({"error": f"unknown wiki action: {action}"}, False)
elif name == "search_package":
action_type = str(arguments.get("action", ""))
pkg_name = str(arguments.get("name", ""))
if action_type == "npm_get_version":
r = await npm_get_version(name=pkg_name, version=str(arguments.get("version","")))
elif action_type == "pypi_versions":
r = await get_pypi_versions(name=pkg_name)
elif action_type == "crates_get_version":
r = await crates_get_version(name=pkg_name, version=str(arguments.get("version","")))
elif action_type == "pypi_get_version":
r = await get_pypi_version(name=pkg_name, version=str(arguments.get("version","")))
elif action_type == "crates_get_readme":
r = await crates_get_readme(name=pkg_name, version=str(arguments.get("version","")))
elif action_type == "crates_summary":
r = await crates_get_summary()
elif action_type == "depsdev_dependencies":
_purl = pkg_name
if _purl.startswith("pkg:"):
_purl = _purl[4:]
if "@" in _purl:
_purl, ver = _purl.rsplit("@", 1)
arguments["version"] = ver # surface parsed version
parts = _purl.split("/", 1)
system = parts[0] if len(parts) > 1 else "npm"
pkg = parts[1] if len(parts) > 1 else _purl
r = await get_resolved_dependencies(system, pkg, str(arguments.get("version", "")))
elif action_type == "depsdev_info":
_purl = pkg_name
if _purl.startswith("pkg:"):
_purl = _purl[4:]
parts = _purl.split("/", 1)
system = parts[0] if len(parts) > 1 else "npm"
pkg = parts[1] if len(parts) > 1 else _purl
r = await get_depsdev_package_info(system, pkg)
elif action_type == "depsdev_advisory":
r = await get_advisory(advisory_id=str(arguments.get("advisory_id","")))
elif action_type == "depsdev_query":
r = await query_by_hash(
hash_type=str(arguments.get("hash_type","SHA256")),
hash_value=str(arguments.get("hash_value","")))
else:
r = await search_package(
name=pkg_name,
registry=str(arguments.get("registry", "auto")),
type=action_type,
)
return _res(r, r.get("success", False))
elif name == "pkg":
action = str(arguments.get("action", "info"))
pkg_name = str(arguments.get("name", ""))
registry = str(arguments.get("registry", "auto"))
if action == "changelog":
r = await get_pkg_changelog(
name=pkg_name, registry=registry,
from_version=str(arguments.get("from_version", "")),
to_version=str(arguments.get("to_version", "")),
count=int(arguments.get("count", 10)))
elif action == "upgrade_review":
r = await get_pkg_upgrade_review(
name=pkg_name, registry=registry,
current_version=str(arguments.get("current_version", "")),
target_version=str(arguments.get("target_version", "")))
elif action == "files":
r = await list_package_files(
name=pkg_name, registry=registry,
version=str(arguments.get("version", "")),
path_filter=str(arguments.get("path", "")))
elif action == "read":
r = await read_package_file(
name=pkg_name, registry=registry,
path=str(arguments.get("path", "")),
version=str(arguments.get("version", "")))
else: # info
pkg_info = await resolve_package(registry, pkg_name)
r = pkg_info
enrichment_errors: list[str] = []
if pkg_info.get("success"):
try:
lib_info = await search_libraries_io(
name=pkg_name, platform=pkg_info["registry"])
if lib_info.get("success"):
r["libraries_io"] = lib_info
except Exception as e:
enrichment_errors.append(f"libraries_io: {type(e).__name__}: {e}")
try:
# M5: pass the resolved version — version-less PURLs always
# return empty from Sonatype Guide, so the count was 0.
vname = pkg_name
if pkg_info.get("version"):
vname = f"{pkg_name}@{pkg_info['version']}"
vuln_info = await scan_vulnerabilities(
platform=pkg_info["registry"], name=vname)
if vuln_info.get("success"):
vulns_list = (vuln_info.get("reports") or [{}])[0].get("vulnerabilities", [])
r["vulnerabilities"] = len(vulns_list)
if vuln_info.get("fallback"):
r["vuln_source"] = vuln_info["fallback"]
# Surface the worst severity + KEV-exploited ids.
sev_rank = {"critical": 4, "high": 3, "medium": 2, "low": 1}
worst = max(vulns_list,
key=lambda v: sev_rank.get(str(v.get("severity", "")).lower(), 0),
default=None)
if worst:
r["worst_severity"] = worst.get("severity", "")
exploited = [v.get("id", "") for v in vulns_list if v.get("exploited")]
if exploited:
r["exploited"] = exploited
except Exception as e:
enrichment_errors.append(f"vulnerabilities: {type(e).__name__}: {e}")
try:
# GHSA severity enrichment for the package ecosystem.
eco_map = {"npm": "npm", "pypi": "pip", "crates": "rust"}
eco = eco_map.get(pkg_info["registry"], "")
if eco:
g = await _ghsa_search(ecosystem=eco, count=5)
if g.get("success") and g.get("advisories"):
r["ghsa_recent"] = [
{"id": a.get("ghsa_id", ""), "cve": a.get("cve_id", ""),
"severity": a.get("severity", ""),
"summary": (a.get("summary", "") or "")[:200]}
for a in g["advisories"][:5]]
except Exception as e:
enrichment_errors.append(f"ghsa: {type(e).__name__}: {e}")
try:
# OpenSSF Scorecard health when the package maps to GitHub.
owner = pkg_info.get("repo_owner", "")
repo_name = pkg_info.get("repo_name", "")
if owner and repo_name:
sc = await scorecard_score(owner, repo_name)
if sc.get("success"):
card = sc["scorecard"]
r["scorecard"] = {
"score": card.get("score", 0),
"date": card.get("date", ""),
"checks": [
{"name": c.get("name", ""), "score": c.get("score", 0)}
for c in card.get("checks", [])][:10],
}
except Exception as e:
enrichment_errors.append(f"scorecard: {type(e).__name__}: {e}")
if enrichment_errors:
r["enrichment_errors"] = enrichment_errors
return _res(r, r.get("success", False))
elif name == "so_search":
action = str(arguments.get("action", "stackexchange"))
if action == "sofa":
r = await search_sofa(
query=str(arguments.get("query", "")),
count=int(arguments.get("count", 5)),