zzstoatzz.io
MCP server for tangled
remove NEXT_STEPS.md from tracking
-137
NEXT_STEPS.md
-137
NEXT_STEPS.md
···
1
-
# next steps
2
-
3
-
## critical fixes
4
-
5
-
### 1. label validation must fail loudly
6
-
7
-
**problem:** when users specify labels that don't exist in the repo's subscribed label definitions, they're silently ignored. no error, no warning, just nothing happens.
8
-
9
-
**current behavior:**
10
-
```python
11
-
create_repo_issue(repo="owner/repo", labels=["demo", "nonexistent"])
12
-
# -> creates issue with NO labels, returns success
13
-
```
14
-
15
-
**what should happen:**
16
-
```python
17
-
create_repo_issue(repo="owner/repo", labels=["demo", "nonexistent"])
18
-
# -> raises ValueError:
19
-
# "invalid labels: ['demo', 'nonexistent']
20
-
# available labels for this repo: ['wontfix', 'duplicate', 'good-first-issue', ...]"
21
-
```
22
-
23
-
**fix locations:**
24
-
- `src/tangled_mcp/_tangled/_issues.py:_apply_labels()` - validate before applying
25
-
- add `validate_labels()` helper that checks against repo's subscribed labels
26
-
- fail fast with actionable error message listing available labels
27
-
28
-
### 2. list_repo_issues should include label information
29
-
30
-
**problem:** `list_repo_issues` returns issues but doesn't include their labels. labels are stored separately in `sh.tangled.label.op` records and need to be fetched and correlated.
31
-
32
-
**impact:** users can't see what labels an issue has without manually querying label ops or checking the UI.
33
-
34
-
**fix:**
35
-
- add `labels: list[str]` field to `IssueInfo` model
36
-
- in `list_repo_issues`, fetch label ops and correlate with issues
37
-
- return label names (not URIs) for better UX
38
-
39
-
### 3. fix pydantic field warning
40
-
41
-
**warning:**
42
-
```
43
-
UnsupportedFieldAttributeWarning: The 'default' attribute with value None was provided
44
-
to the `Field()` function, which has no effect in the context it was used.
45
-
```
46
-
47
-
**likely cause:** somewhere we're using `Field(default=None)` in an `Annotated` type or union context where it doesn't make sense.
48
-
49
-
**fix:** audit all `Field()` uses and remove invalid `default=None` declarations.
50
-
51
-
## enhancements
52
-
53
-
### 4. better error messages for repo resolution failures
54
-
55
-
when a repo doesn't exist or handle can't be resolved, give users clear next steps:
56
-
- is the repo name spelled correctly?
57
-
- does the repo exist on tangled.org?
58
-
- do you have access to it?
59
-
60
-
### 5. add label listing tool
61
-
62
-
users need to know what labels are available for a repo before they can use them.
63
-
64
-
**new tool:**
65
-
```python
66
-
list_repo_labels(repo: str) -> list[str]
67
-
# returns: ["wontfix", "duplicate", "good-first-issue", ...]
68
-
```
69
-
70
-
### 6. pagination cursor handling
71
-
72
-
currently returning raw cursor strings. consider:
73
-
- documenting cursor format
74
-
- providing helper for "has more pages" checking
75
-
- clear examples in docstrings
76
-
77
-
## completed improvements (this session)
78
-
79
-
### ✅ types architecture refactored
80
-
- moved from single `types.py` to `types/` directory
81
-
- separated concerns: `_common.py`, `_branches.py`, `_issues.py`
82
-
- public API in `__init__.py`
83
-
- parsing logic moved into types via `.from_api_response()` class methods
84
-
85
-
### ✅ proper validation with annotated types
86
-
- `RepoIdentifier = Annotated[str, AfterValidator(normalize_repo_identifier)]`
87
-
- strips `@` prefix automatically
88
-
- validates format before processing
89
-
90
-
### ✅ clickable URLs instead of AT Protocol internals
91
-
- issue operations return `https://tangled.org/@owner/repo/issues/N`
92
-
- removed useless `uri` and `cid` from user-facing responses
93
-
- URL generation encapsulated in types via `@computed_field`
94
-
95
-
### ✅ proper typing everywhere
96
-
- no more `dict[str, Any]` return types
97
-
- pydantic models for all results
98
-
- type safety throughout
99
-
100
-
### ✅ minimal test coverage
101
-
- 17 tests covering public contracts
102
-
- no implementation details tested
103
-
- validates key behaviors: URL generation, validation, parsing
104
-
105
-
### ✅ demo scripts
106
-
- full lifecycle demo
107
-
- URL format handling demo
108
-
- branch listing demo
109
-
- label manipulation demo (revealed silent failure issue)
110
-
111
-
### ✅ documentation improvements
112
-
- MCP client installation instructions in collapsible details
113
-
- clear usage examples for multiple clients
114
-
115
-
## technical debt
116
-
117
-
### remove unused types
118
-
- `RepoInfo`, `PullInfo`, `CreateRepoResult`, `GenericResult` - not used anywhere
119
-
- clean up or remove from public API
120
-
121
-
### consolidate URL generation logic
122
-
- `_tangled_issue_url()` helper was created to DRY the URL generation
123
-
- good pattern, consider extending to other URL types if needed
124
-
125
-
### consider lazy evaluation for expensive validations
126
-
- repo resolution happens on every tool call
127
-
- could cache repo metadata (knot, did) for duration of connection
128
-
- tradeoff: freshness vs performance
129
-
130
-
## priorities
131
-
132
-
1. **critical:** fix label validation (fails silently)
133
-
2. **high:** add labels to list_repo_issues output
134
-
3. **medium:** add list_repo_labels tool
135
-
4. **medium:** fix pydantic warning
136
-
5. **low:** better error messages
137
-
6. **low:** clean up unused types