sifs 0.3.3

SIFS Is Fast Search: instant local code search for agents
Documentation 
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

# MCP server usage

SIFS can run as a local Model Context Protocol server over stdio. The MCP
surface mirrors the agent-native CLI vocabulary: use `source` for local paths or
Git URLs, `limit` for bounded result counts, and `list_files` for indexed file
inventory.

MCP is optional for agent integration. The `sifs agent` command can install
CLI-first skills and snippets that tell agents to fall back to shell commands
when MCP tools are not visible in the current session.

## Start the server

```bash
target/release/sifs mcp
target/release/sifs mcp --source /path/to/project
target/release/sifs mcp --source https://github.com/owner/project --ref main
```

When a default source is configured, tools can omit `source`. Calls can still
pass another `source` when an agent needs a different local checkout or Git URL.
`--offline` rejects Git URL sources and disables model downloads.

## Install into Codex or Claude Code

```bash
sifs daemon install-agent
sifs mcp install --client all
sifs mcp install --client all --source /path/to/project
sifs mcp install --client codex --source /path/to/project
sifs mcp install --client claude --scope local --source /path/to/project
```

Use `--dry-run --json` when an agent needs the exact command arrays and fallback
config without mutating client state.

```bash
sifs mcp install --dry-run --json --client all
```

Use `sifs mcp doctor --json` for machine-readable readiness checks. The doctor
keeps MCP startup handshakes separate from BM25 search smoke.

```bash
sifs mcp doctor --source /path/to/project --offline --no-cache --json
```

## Protocol surface

`initialize` is lightweight and does not build an index. Index work happens
during tool calls such as `search`, `index_status`, and `refresh_index`.

Supported methods:

- `initialize`
- `resources/list`
- `resources/read`
- `tools/list`
- `tools/call`

Supported resources:

- `sifs://server/context`
- `sifs://agent/context`
- `sifs://profiles`
- `sifs://feedback`
- `sifs://index/status`
- `sifs://index/files`

## Tools

Core tools:

- `agent_context`: return the versioned CLI/MCP contract.
- `agent_print`: render a SIFS skill, snippet, or MCP guidance artifact without
  writing files.
- `agent_doctor`: inspect agent artifact readiness; reports `unknown` when
  current-session visibility cannot be proven.
- `search`: search chunks by natural language, code, or symbol query.
- `find_related`: find chunks related to a known file and line.
- `index_status`: inspect the selected source.
- `refresh_index`: rebuild the selected in-memory index.
- `clear_index`: remove the selected source from the in-memory MCP cache.
- `list_files`: list repository-relative indexed file paths.
- `get_chunk`: read the indexed chunk containing a file and line.
- `init_agent`: compatibility helper for writing the Claude Code SIFS agent
  file. Prefer `agent_print` plus CLI `sifs agent install` for new
  target-aware workflows.

Profile and feedback tools:

- `profile_list`
- `profile_show`
- `feedback_create`
- `feedback_list`

## Search tool

Input schema:

```json
{
  "query": "Natural language or code query.",
  "source": "/path/to/project",
  "profile": "sifs-dev",
  "mode": "hybrid",
  "limit": 5,
  "filter_languages": ["rust"],
  "filter_paths": ["src/main.rs"]
}
```

Fields:

- `query` is required.
- `source` is optional when the server has a default source or `profile`
  provides one.
- `profile` is optional and uses saved source/search defaults.
- `mode` is `hybrid`, `semantic`, or `bm25`; defaults to the profile's mode if set, otherwise `hybrid`.
- `limit` defaults to the profile's limit if set, otherwise `5`.
- `alpha` optionally controls hybrid semantic weight.
- `filter_languages` and `filter_paths` narrow the indexed chunks searched.

Invalid modes and invalid limits are rejected instead of silently defaulting.
Structured search results include `limit`, `truncated`, warnings, index stats,
and result rows.

## Index inspection

```json
{"source": "/path/to/project"}
```

Use that shape with `index_status`, `refresh_index`, and `clear_index`.

Use `list_files` with a bounded limit:

```json
{"source": "/path/to/project", "limit": 200}
```

Use `get_chunk` with a file and one-based line:

```json
{"source": "/path/to/project", "file_path": "src/auth.rs", "line": 42}
```

## Profiles and feedback

Profiles are saved through the CLI and discoverable through MCP:

```json
{}
```

Call `profile_list` to enumerate profiles, then `profile_show` with a name.

Feedback is local-first:

```json
{"message": "mode=lexical should enumerate valid modes"}
```

Call `feedback_create` to append a local feedback entry and `feedback_list` to
inspect bounded recent entries.

## Breaking vocabulary

The agent-native surface intentionally uses `source` instead of `repo`, `limit`
instead of `top_k`, and `list_files` instead of `list_indexed_files`. Old names
are rejected so agents learn one contract instead of carrying ambiguous aliases.