odd-tool 0.5.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.
- odd.py +5382 -0
- odd_mcp.py +215 -0
- odd_tool-0.5.0.dist-info/METADATA +488 -0
- odd_tool-0.5.0.dist-info/RECORD +8 -0
- odd_tool-0.5.0.dist-info/WHEEL +5 -0
- odd_tool-0.5.0.dist-info/entry_points.txt +3 -0
- odd_tool-0.5.0.dist-info/licenses/LICENSE +21 -0
- odd_tool-0.5.0.dist-info/top_level.txt +2 -0
odd_mcp.py
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""odd_mcp: odd's commands as MCP tools, so a coding agent calls them as tools instead of through a shell.
|
|
3
|
+
|
|
4
|
+
Speaks MCP over stdio: JSON-RPC 2.0, one message per line. Each tool runs odd.py (the file beside this one) as a
|
|
5
|
+
subprocess in the server's working directory and returns its exit code and everything it printed: 0 pass, 1 fail or
|
|
6
|
+
not shown, 2 could not run. Nothing odd decides is repeated here.
|
|
7
|
+
|
|
8
|
+
Dual-era: it answers the stateless 2026-07-28 revision (server/discover, the version in each request's _meta) and
|
|
9
|
+
the initialize handshake of 2025-11-25 and earlier. `odd init --mcp` copies this file to .odd/ and adds it to the
|
|
10
|
+
project's .mcp.json. Standard library only, Python 3.8+.
|
|
11
|
+
"""
|
|
12
|
+
import json
|
|
13
|
+
import os
|
|
14
|
+
import subprocess
|
|
15
|
+
import sys
|
|
16
|
+
|
|
17
|
+
MODERN = '2026-07-28'
|
|
18
|
+
LEGACY = ('2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05')
|
|
19
|
+
VERSION_KEY = 'io.modelcontextprotocol/protocolVersion'
|
|
20
|
+
ODD_PY = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'odd.py')
|
|
21
|
+
MEANING = {0: 'pass', 1: 'fail / not shown', 2: 'could not run'}
|
|
22
|
+
S, B = {'type': 'string'}, {'type': 'boolean'}
|
|
23
|
+
SLUG = ('slug', S, 'the outcome, as named in .odd/outcomes/<slug>.md')
|
|
24
|
+
BASE = ('base', S, 'measure from this revision instead of the target branch')
|
|
25
|
+
NOCACHE = ('no-cache', B, 'verify in full even when the inputs match an earlier verification')
|
|
26
|
+
POSITIONAL = ('slug', 'ticket', 'outcome', 'reason', 'what', 'question')
|
|
27
|
+
TOOLS = ( # name, description, arguments (name, schema, description), the required ones
|
|
28
|
+
('new', 'State an outcome before the code: writes .odd/outcomes/<slug>.md. proof "auto" picks a narrow command '
|
|
29
|
+
'from the test runner the repository uses and says what it detected. Ends with "read these first": the files '
|
|
30
|
+
'inside the boundary (largest change first, at most ten) and the files the proof names.',
|
|
31
|
+
[SLUG, ('outcome', S, 'one sentence: who observes what result'),
|
|
32
|
+
('proof', S, 'a command that exits 0 only when the outcome holds, or "auto" (optional with kind "refactor": '
|
|
33
|
+
'the whole suite)'),
|
|
34
|
+
('in', S, 'globs of the product files the change may touch, comma-separated'),
|
|
35
|
+
('test', S, 'with proof "auto": the test file the proof runs'),
|
|
36
|
+
('covers', S, 'the requirements this outcome covers, comma-separated: R1, R3 (.odd/requirements/<ticket>.md)'),
|
|
37
|
+
('kind', S, '"bug": seal and done require the proof to fail at the base revision (reproduce first); "feature": '
|
|
38
|
+
'the proof covers the new behaviour; "refactor": the proof defaults to the whole suite and the '
|
|
39
|
+
'take-out check is skipped')],
|
|
40
|
+
('slug', 'outcome', 'in')),
|
|
41
|
+
('seal', 'Optional, before the code: the proof must fail now; fingerprints the test files so a later edit shows.',
|
|
42
|
+
[SLUG, BASE], ('slug',)),
|
|
43
|
+
('done', 'Verify an outcome: the proof passes, fails with the change taken out, and passes again.',
|
|
44
|
+
[SLUG, BASE, NOCACHE], ('slug',)),
|
|
45
|
+
('gate', 'Check the whole change: every changed product file is inside one verified outcome or an exemption.',
|
|
46
|
+
[BASE, ('recompute', B, 'trust nothing recorded: verify every outcome again (as CI does)'), NOCACHE], ()),
|
|
47
|
+
('check', 'No setup, no outcome file: run the test files this change brings, take the rest of the change out and run '
|
|
48
|
+
'them again. Says SHOWN (they fail without it), NOT SHOWN (they pass without it, or do not pass), NO '
|
|
49
|
+
'CHANGE (only test files changed) or NOT CHECKED (the change has no test of its own).',
|
|
50
|
+
[BASE, ('proof', S, 'the command to run, instead of the test files this change brings'),
|
|
51
|
+
('tests', S, 'more paths that hold tests, comma-separated globs'),
|
|
52
|
+
('require-change', B, 'exit 1 when only test files changed and they pass')], ()),
|
|
53
|
+
('reread', 'Advisory: another agent writes a proof from the request at the base, where it cannot see the change; '
|
|
54
|
+
'the proof must fail there and is then run on the change. Exit 1 when it fails on the change: two '
|
|
55
|
+
'readings of the request disagree and one is wrong. Nothing is applied.',
|
|
56
|
+
[SLUG, ('by', S, 'the second reader\'s agent command (default: "reasoner", else the first of "agents")'),
|
|
57
|
+
('ticket', S, 'a file holding the request as the person wrote it'), BASE], ('slug',)),
|
|
58
|
+
('race', 'Run the outcome as N parallel agent attempts, each in its own git worktree; each is verified as done '
|
|
59
|
+
'would, and the verified one with the strongest proof and fewest changed lines is applied.',
|
|
60
|
+
[SLUG, ('n', S, 'how many attempts, as a number (default: one per configured agent, or 3)'),
|
|
61
|
+
('agent', S, 'the agent command for every attempt, instead of "agents" in .odd/config.json'), BASE, NOCACHE], ('slug',)),
|
|
62
|
+
('cascade', 'Try the outcome with the configured agents in order, cheapest first, each attempt in its own git '
|
|
63
|
+
'worktree and verified as done would; escalate to the next agent, with the failure passed on, only when '
|
|
64
|
+
'no attempt is verified; park the outcome with every reason after the last.',
|
|
65
|
+
[SLUG, ('agents', S, 'agent commands, cheapest first, comma-separated (default: "agents" in .odd/config.json)'),
|
|
66
|
+
('race', S, 'attempts per level in parallel, as a number (default 1)'), BASE, NOCACHE], ('slug',)),
|
|
67
|
+
('chain', 'Do a long task as a chain of proven outcomes: .odd/chains/<ticket>.md lists outcome slugs in order; each '
|
|
68
|
+
'one not yet proven is attempted as race (or cascade) would, verified, and committed as the checkpoint '
|
|
69
|
+
'"odd: <slug> proven". An unproven one stops the chain, the tree is back at the last checkpoint and the '
|
|
70
|
+
'outcome is parked with the reasons; calling it again continues from the first unproven outcome.',
|
|
71
|
+
[('ticket', S, 'the chain, as named in .odd/chains/<ticket>.md'),
|
|
72
|
+
('race', S, 'attempts per outcome in parallel, as a number (with cascade: per level, default 1)'),
|
|
73
|
+
('cascade', B, 'attempt each outcome with the agents in order, cheapest first, as cascade does'),
|
|
74
|
+
('agents', S, 'agent commands, comma-separated (default: "agents" in .odd/config.json)'), BASE, NOCACHE], ('ticket',)),
|
|
75
|
+
('spec', 'Have another agent (in practice a stronger model) write only the proof, in its own git worktree; the '
|
|
76
|
+
'test files come back and are sealed red before any code; retried, then parked, if the proof does not '
|
|
77
|
+
'fail first.',
|
|
78
|
+
[SLUG, ('proof-by', S, 'the agent command that writes the proof; {prompt_file} becomes the prompt path, else stdin'),
|
|
79
|
+
('tries', S, 'tries for a proof that fails before the code, as a number (default 3)'), BASE], ('slug', 'proof-by')),
|
|
80
|
+
('park', 'The honest exit: the outcome is blocked or cannot be done as specified.',
|
|
81
|
+
[SLUG, ('reason', S, 'why')], ('slug', 'reason')),
|
|
82
|
+
('ask', 'The outcome cannot be made checkable from the ticket: record one precise question; the gate reports the '
|
|
83
|
+
'outcome as waiting for an answer until its "asked:" line is deleted.',
|
|
84
|
+
[SLUG, ('question', S, 'one precise question, ending in "?"')], ('slug', 'question')),
|
|
85
|
+
('escaped', 'Record a defect that got past a merged outcome.',
|
|
86
|
+
[SLUG, ('what', S, 'what went wrong, and where it was found')], ('slug', 'what')),
|
|
87
|
+
('stats', 'Counts, self-reported: per outcome, escaped defects grouped by outcome kind, seal, proof strength band '
|
|
88
|
+
'and proof author (rate per group; a group under 10 outcomes is said to be small), and cost per proven '
|
|
89
|
+
'outcome.',
|
|
90
|
+
[('json', B, 'the same counts as JSON')], ()),
|
|
91
|
+
)
|
|
92
|
+
OUTPUT = {'type': 'object', 'properties': {'exit_code': {'type': 'integer'}, 'output': {'type': 'string'},
|
|
93
|
+
'next': {'type': 'array', 'items': {'type': 'string'}}},
|
|
94
|
+
'required': ['exit_code', 'output']}
|
|
95
|
+
INFO = {'name': 'odd', 'version': '1'}
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
class RpcError(Exception):
|
|
99
|
+
def __init__(self, code, message, data=None):
|
|
100
|
+
Exception.__init__(self, message)
|
|
101
|
+
self.code, self.data = code, data
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def tool_list():
|
|
105
|
+
return [{'name': name, 'description': text, 'outputSchema': OUTPUT,
|
|
106
|
+
'inputSchema': {'type': 'object', 'additionalProperties': False, 'required': list(req),
|
|
107
|
+
'properties': {k: dict(schema, description=d) for k, schema, d in args}}}
|
|
108
|
+
for name, text, args, req in TOOLS]
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def argv_for(name, given):
|
|
112
|
+
"""odd's command line for one tool call; arguments of the wrong name or kind are refused before odd runs."""
|
|
113
|
+
spec = [t for t in TOOLS if t[0] == name]
|
|
114
|
+
if not spec:
|
|
115
|
+
raise RpcError(-32602, 'unknown tool: %s (the tools are: %s)' % (name, ', '.join(t[0] for t in TOOLS)))
|
|
116
|
+
_, _, args, req = spec[0]
|
|
117
|
+
kinds = {k: schema['type'] for k, schema, _ in args}
|
|
118
|
+
given = given if isinstance(given, dict) else {}
|
|
119
|
+
wrong = [k for k in given if k not in kinds or not isinstance(given[k], bool if kinds[k] == 'boolean' else str)]
|
|
120
|
+
missing = [k for k in req if not given.get(k)]
|
|
121
|
+
if wrong or missing:
|
|
122
|
+
raise RpcError(-32602, 'odd %s: %s' % (name, '; '.join(
|
|
123
|
+
(['not an argument, or the wrong kind of value: ' + ', '.join(wrong)] if wrong else []) +
|
|
124
|
+
(['missing: ' + ', '.join(missing)] if missing else []))))
|
|
125
|
+
flags, pos = [], []
|
|
126
|
+
for k, _, _ in args: # flags first, then "--", so a value starting with "-" is never read as an option
|
|
127
|
+
v = given.get(k)
|
|
128
|
+
if k in POSITIONAL and v is not None:
|
|
129
|
+
pos.append(v)
|
|
130
|
+
elif v is True:
|
|
131
|
+
flags.append('--' + k)
|
|
132
|
+
elif isinstance(v, str):
|
|
133
|
+
flags += ['--' + k, v]
|
|
134
|
+
return [name] + flags + (['--'] + pos if pos else [])
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def call(name, given):
|
|
138
|
+
argv = argv_for(name, given)
|
|
139
|
+
if not os.path.isfile(ODD_PY):
|
|
140
|
+
return result(2, 'odd: could not run: odd.py is not beside odd_mcp.py (%s)' % ODD_PY, name)
|
|
141
|
+
try:
|
|
142
|
+
r = subprocess.run([sys.executable, ODD_PY] + argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
|
|
143
|
+
stderr=subprocess.STDOUT, universal_newlines=True, errors='replace')
|
|
144
|
+
rc, out = r.returncode, r.stdout
|
|
145
|
+
except OSError as e:
|
|
146
|
+
rc, out = 2, 'odd: could not run: %s (odd_mcp runs %s)' % (e, ODD_PY)
|
|
147
|
+
return result(rc, out, name)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def result(rc, out, name):
|
|
151
|
+
rc = rc if rc in MEANING else 2 # anything else is never reported as a pass or a plain failure
|
|
152
|
+
lines = out.rstrip('\n').split('\n')
|
|
153
|
+
at = [i for i, line in enumerate(lines) if line == 'next:'] # odd's next: block (a failed done, race or cascade)
|
|
154
|
+
more = {'next': [line.strip() for line in lines[at[-1] + 1:]]} if at else {}
|
|
155
|
+
return {'content': [{'type': 'text', 'text': 'odd %s: exit %d (%s)\n%s' % (name, rc, MEANING[rc], out)}],
|
|
156
|
+
'structuredContent': dict({'exit_code': rc, 'output': out}, **more), 'isError': rc != 0}
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def handle(method, params):
|
|
160
|
+
meta_in = params.get('_meta')
|
|
161
|
+
version = meta_in.get(VERSION_KEY) if isinstance(meta_in, dict) else None
|
|
162
|
+
if version is not None and version not in (MODERN,) + LEGACY:
|
|
163
|
+
raise RpcError(-32022, 'Unsupported protocol version', {'supported': [MODERN] + list(LEGACY), 'requested': version})
|
|
164
|
+
if method == 'initialize': # the handshake of 2025-11-25 and earlier
|
|
165
|
+
asked = params.get('protocolVersion')
|
|
166
|
+
return {'protocolVersion': asked if asked in LEGACY else LEGACY[0], 'capabilities': {'tools': {}}, 'serverInfo': INFO}
|
|
167
|
+
meta = {'_meta': {'io.modelcontextprotocol/serverInfo': INFO}, 'resultType': 'complete'}
|
|
168
|
+
if method == 'server/discover':
|
|
169
|
+
return dict(meta, supportedVersions=[MODERN] + list(LEGACY), capabilities={'tools': {}}, ttlMs=3600000,
|
|
170
|
+
cacheScope='public')
|
|
171
|
+
if method == 'tools/list':
|
|
172
|
+
return dict(meta, tools=tool_list(), ttlMs=3600000, cacheScope='public')
|
|
173
|
+
if method == 'tools/call':
|
|
174
|
+
return dict(meta, **call(params.get('name'), params.get('arguments')))
|
|
175
|
+
if method == 'ping':
|
|
176
|
+
return {}
|
|
177
|
+
raise RpcError(-32601, 'method not found: %s' % method)
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def reply(msg):
|
|
181
|
+
"""The answer to one parsed message, or None for a notification."""
|
|
182
|
+
if not isinstance(msg, dict) or not isinstance(msg.get('method'), str):
|
|
183
|
+
return {'jsonrpc': '2.0', 'id': msg.get('id') if isinstance(msg, dict) else None,
|
|
184
|
+
'error': {'code': -32600, 'message': 'invalid request'}}
|
|
185
|
+
if 'id' not in msg:
|
|
186
|
+
return None
|
|
187
|
+
try:
|
|
188
|
+
params = msg.get('params') if isinstance(msg.get('params'), dict) else {}
|
|
189
|
+
return {'jsonrpc': '2.0', 'id': msg['id'], 'result': handle(msg['method'], params)}
|
|
190
|
+
except RpcError as e:
|
|
191
|
+
err = {'code': e.code, 'message': str(e)}
|
|
192
|
+
if e.data is not None:
|
|
193
|
+
err['data'] = e.data
|
|
194
|
+
return {'jsonrpc': '2.0', 'id': msg['id'], 'error': err}
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def main():
|
|
198
|
+
inp = sys.stdin.buffer
|
|
199
|
+
while True:
|
|
200
|
+
line = inp.readline()
|
|
201
|
+
if not line:
|
|
202
|
+
return 0
|
|
203
|
+
if not line.strip():
|
|
204
|
+
continue
|
|
205
|
+
try:
|
|
206
|
+
out = reply(json.loads(line.decode('utf-8', 'replace')))
|
|
207
|
+
except ValueError:
|
|
208
|
+
out = {'jsonrpc': '2.0', 'id': None, 'error': {'code': -32700, 'message': 'parse error'}}
|
|
209
|
+
if out is not None:
|
|
210
|
+
sys.stdout.write(json.dumps(out) + '\n')
|
|
211
|
+
sys.stdout.flush()
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
if __name__ == '__main__':
|
|
215
|
+
sys.exit(main())
|