@spec-r/mcp-server 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -0
- package/dist/index.js +1637 -0
- package/package.json +39 -0
package/README.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# @spec-r/mcp-server
|
|
2
|
+
|
|
3
|
+
MCP server for [spec-r](https://spec-r.app) — give Claude Code and other AI agents direct access to your specifications.
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
**1. Get your API key**
|
|
8
|
+
|
|
9
|
+
Go to [spec-r.app/settings](https://spec-r.app/settings) → API Keys → Create.
|
|
10
|
+
|
|
11
|
+
**2. Add to your MCP config**
|
|
12
|
+
|
|
13
|
+
Per-project (`.mcp.json` at repo root):
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"mcpServers": {
|
|
18
|
+
"spec-r": {
|
|
19
|
+
"command": "npx",
|
|
20
|
+
"args": ["-y", "@spec-r/mcp-server"],
|
|
21
|
+
"env": {
|
|
22
|
+
"SPECR_API_KEY": "specr_xxxxx",
|
|
23
|
+
"SPECR_PROJECT_ID": "your-project-uuid"
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Global (`~/.claude/settings.json` or Claude Desktop config) — omit `SPECR_PROJECT_ID`, the agent will discover projects automatically:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"spec-r": {
|
|
36
|
+
"command": "npx",
|
|
37
|
+
"args": ["-y", "@spec-r/mcp-server"],
|
|
38
|
+
"env": {
|
|
39
|
+
"SPECR_API_KEY": "specr_xxxxx"
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Environment variables
|
|
47
|
+
|
|
48
|
+
| Variable | Required | Description |
|
|
49
|
+
| ------------------ | -------- | ------------------------------------------------- |
|
|
50
|
+
| `SPECR_API_KEY` | Yes | API key from Settings → API Keys |
|
|
51
|
+
| `SPECR_BASE_URL` | No | Override API base URL (default: `https://spec-r.app`) |
|
|
52
|
+
| `SPECR_PROJECT_ID` | No | Default project UUID — skip to let the agent discover it |
|
|
53
|
+
|
|
54
|
+
## Tools
|
|
55
|
+
|
|
56
|
+
### Discovery
|
|
57
|
+
|
|
58
|
+
| Tool | Description |
|
|
59
|
+
| --------------------- | -------------------------------------------------------------- |
|
|
60
|
+
| `list_projects` | List all projects and their UUIDs |
|
|
61
|
+
| `list_specs` | List all specs in a project |
|
|
62
|
+
| `get_spec` | Get a spec with all blocks (`agent`, `markdown`, or `json`) |
|
|
63
|
+
| `search_specs` | Search specs and blocks by keyword |
|
|
64
|
+
| `get_project_context` | Get project tech stack, industry, and conventions |
|
|
65
|
+
| `get_data_models` | Get all data models defined across specs in a project |
|
|
66
|
+
|
|
67
|
+
### Write
|
|
68
|
+
|
|
69
|
+
| Tool | Description |
|
|
70
|
+
| ---------------- | ----------------------------------------------------------------- |
|
|
71
|
+
| `create_project` | Create a new project with name, tech stack, and conventions |
|
|
72
|
+
| `update_project` | Update project metadata, tech stack, or conventions |
|
|
73
|
+
| `publish_spec` | Create or update a spec by title (upsert with blocks) |
|
|
74
|
+
| `create_spec` | Create an empty spec |
|
|
75
|
+
| `add_block` | Add a typed block to a spec |
|
|
76
|
+
| `update_block` | Update a block's content |
|
|
77
|
+
| `delete_block` | Delete a block |
|
|
78
|
+
| `update_spec` | Update spec title, type, or status |
|
|
79
|
+
|
|
80
|
+
### Shared resources
|
|
81
|
+
|
|
82
|
+
Shared resources are reusable entities (`data_model`, `persona`, `enum_definition`, `external_dependency`) defined once at the project level and referenced from any spec block via `linkedResourceId`.
|
|
83
|
+
|
|
84
|
+
| Tool | Description |
|
|
85
|
+
| ----------------- | --------------------------------------------------- |
|
|
86
|
+
| `list_resources` | List shared resources, optionally filtered by type |
|
|
87
|
+
| `get_resource` | Get a resource and see which specs reference it |
|
|
88
|
+
| `create_resource` | Create a shared resource |
|
|
89
|
+
| `update_resource` | Update a shared resource |
|
|
90
|
+
| `delete_resource` | Delete a shared resource |
|
|
91
|
+
|
|
92
|
+
### Implementation tracking
|
|
93
|
+
|
|
94
|
+
| Tool | Description |
|
|
95
|
+
| ------------------------------ | ------------------------------------------------------------------- |
|
|
96
|
+
| `get_implementation_status` | Get progress and per-step status for a spec |
|
|
97
|
+
| `update_implementation_status` | Mark a step as `pending`, `in_progress`, `done`, or `blocked` |
|
|
98
|
+
|
|
99
|
+
### AI analysis
|
|
100
|
+
|
|
101
|
+
| Tool | Description |
|
|
102
|
+
| ------------------- | ------------------------------------------------------------------------ |
|
|
103
|
+
| `analyze_screenshot`| Analyze a wireframe/mockup and extract structured specs |
|
|
104
|
+
| `analyze_feedback` | Analyze client feedback and extract prioritized feature requests |
|
|
105
|
+
|
|
106
|
+
## Resources
|
|
107
|
+
|
|
108
|
+
The server exposes MCP resources for passive reading without tool calls:
|
|
109
|
+
|
|
110
|
+
| URI | Description |
|
|
111
|
+
| -------------------------------------------- | ---------------------------------------- |
|
|
112
|
+
| `spec-r://block-types` | Schema reference for all 25 block types |
|
|
113
|
+
| `spec-r://projects/{projectId}/specs` | Spec list for a project |
|
|
114
|
+
| `spec-r://projects/{projectId}/resources` | Shared resources for a project |
|
|
115
|
+
| `spec-r://specs/{specId}` | Full spec content |
|
|
116
|
+
|
|
117
|
+
Before calling `publish_spec` or `add_block`, read `spec-r://block-types` to get the exact content schema for each block type.
|
|
118
|
+
|
|
119
|
+
## Tips
|
|
120
|
+
|
|
121
|
+
- Omit `SPECR_PROJECT_ID` in global configs — the agent uses `list_projects` to discover IDs
|
|
122
|
+
- Use `get_spec` with `format: "agent"` for the most implementation-ready output
|
|
123
|
+
- Define cross-cutting entities (User, enums, external APIs) as shared resources with `create_resource` — avoids repeating the same data model in every spec
|
|
124
|
+
- Use `update_implementation_status` to track progress as you code — attach commit SHAs and PR URLs
|
|
125
|
+
|
|
126
|
+
## License
|
|
127
|
+
|
|
128
|
+
MIT
|