oscar64-mcp-docs 0.1.1
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.
- package/README.md +124 -0
- package/dist/stdio.d.ts +1 -0
- package/dist/stdio.js +1260 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# oscar64-mcp-docs
|
|
2
|
+
|
|
3
|
+
Local MCP server (Mastra + stdio) exposing Oscar64 documentation and tutorial code examples.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- HTTP-only source syncing (no git dependency)
|
|
8
|
+
- 24h stale checks with remote SHA + local zip hash detection
|
|
9
|
+
- Anchored manual retrieval (`docs://oscar64/manual#...`)
|
|
10
|
+
- Tutorial manifests generated from folder structure and source previews
|
|
11
|
+
- Generic concept classifier with evidence + concept-derived categories
|
|
12
|
+
- MiniSearch-powered doc/tutorial relevance search
|
|
13
|
+
- Scoped code search (`tutorials`, `sdk`, `samples`, `autotest`, `compiler`)
|
|
14
|
+
- Contract-first MCP tool responses with explicit `next_actions`
|
|
15
|
+
- LLM guidance resources (`index://quickstart`, `index://tooling-guide`, `index://contracts`, `index://errors`)
|
|
16
|
+
|
|
17
|
+
## Development
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install
|
|
21
|
+
npm run check
|
|
22
|
+
npm run test
|
|
23
|
+
npm run dev
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Mastra Studio
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm run studio
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Inspector mode:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm run studio:inspect
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Break on start:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npm run studio:inspect-brk
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Build
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm run build
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The executable entry is built to `dist/stdio.js`.
|
|
51
|
+
|
|
52
|
+
## MCP Interface
|
|
53
|
+
|
|
54
|
+
Primary tools:
|
|
55
|
+
|
|
56
|
+
- `search_docs(query, limit, scope)` -> ranked doc/tutorial hits with `uri`, `title`, `snippet`
|
|
57
|
+
- `get_doc_section(anchor_or_heading, max_chars)` -> resolved manual section content
|
|
58
|
+
- `search_code(query, scope, path_glob, limit)` -> code snippets with `line_start`, `line_end`, `uri`
|
|
59
|
+
- `get_best_tutorial(task, limit)` -> ranked tutorial manifests with concepts and evidence
|
|
60
|
+
- `refresh_sources(force)` -> refresh HTTP snapshots
|
|
61
|
+
- `get_source_status()` -> source readiness and index sizes
|
|
62
|
+
|
|
63
|
+
Standard tool output envelope:
|
|
64
|
+
|
|
65
|
+
- `ok`: success flag
|
|
66
|
+
- `data`: tool payload on success
|
|
67
|
+
- `error`: structured error payload on failure
|
|
68
|
+
- `next_actions`: suggested follow-up calls/resources for the agent
|
|
69
|
+
- `meta`: contract version, generation time, and tool id
|
|
70
|
+
|
|
71
|
+
Reference resources:
|
|
72
|
+
|
|
73
|
+
- `index://quickstart`
|
|
74
|
+
- `index://tooling-guide`
|
|
75
|
+
- `index://contracts`
|
|
76
|
+
- `index://errors`
|
|
77
|
+
|
|
78
|
+
## Versioning
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npm run version:patch
|
|
82
|
+
# or
|
|
83
|
+
npm run version:minor
|
|
84
|
+
# or
|
|
85
|
+
npm run version:major
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Publish to npmjs
|
|
89
|
+
|
|
90
|
+
Dry run:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npm run publish:npm -- --dry-run
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Publish:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npm run publish:npm
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`publish:npm` is interactive:
|
|
103
|
+
- warns on dirty git working tree
|
|
104
|
+
- asks for version bump (`patch/minor/major/custom/keep`)
|
|
105
|
+
- runs `check` + `build`
|
|
106
|
+
- asks for final publish confirmation
|
|
107
|
+
- only mutates `package.json` version after confirmation
|
|
108
|
+
|
|
109
|
+
Optional env vars:
|
|
110
|
+
|
|
111
|
+
- `NPM_ACCESS` (`public` or `restricted`, default `public`)
|
|
112
|
+
- `NPM_TAG` (default `latest`)
|
|
113
|
+
- `NPM_OTP` (for 2FA)
|
|
114
|
+
|
|
115
|
+
## Tutorial Classification Config
|
|
116
|
+
|
|
117
|
+
Classification policy is data-driven in:
|
|
118
|
+
|
|
119
|
+
- `src/config/tutorial-classification.ts`
|
|
120
|
+
|
|
121
|
+
This file defines:
|
|
122
|
+
|
|
123
|
+
- factual concept rules (`CONCEPT_RULES`) using regex patterns + evidence reasons
|
|
124
|
+
- concept groups for top-level categories (`CATEGORY_FROM_CONCEPTS`)
|
package/dist/stdio.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
#!/usr/bin/env node
|