xonecas.io
6119
My

mysis / files

mysis / documentation / architecture / CREDENTIAL_TOOLS.md

4.3 KB
1# Credential Management Tools
2
3Added two MCP tools for session-scoped credential storage:
4
5## Implementation
6
7### Database Schema
8
9Added `session_credentials` table to store game credentials per session:
10
11```sql
12CREATE TABLE IF NOT EXISTS session_credentials (
13    session_id TEXT PRIMARY KEY,
14    username TEXT NOT NULL,
15    password TEXT NOT NULL,
16    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
17    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
18    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
19);
20```
21
22**Key features:**
23
24- One credential pair per session (PRIMARY KEY on session_id)
25- Automatic cleanup via CASCADE when session is deleted
26- Foreign keys enabled in SQLite connection string
27
28### Store Functions
29
30**`internal/store/store.go`:**
31
32- `SaveCredentials(sessionID, username, password)` - Upsert credentials
33- `GetCredentials(sessionID) (username, password, error)` - Retrieve credentials
34- Returns empty strings if no credentials saved (not an error)
35
36### MCP Tools
37
38**`internal/mcp/tools.go`:**
39
40#### `save_credentials`
41
42Saves username and password for the current session.
43
44**Input Schema:**
45
46```json
47{
48  "username": "string (required)",
49  "password": "string (required)"
50}
51```
52
53**Response:**
54
55```
56Credentials saved successfully for user 'username'
57```
58
59**Validation:**
60
61- Username cannot be empty
62- Password cannot be empty
63
64#### `get_credentials`
65
66Retrieves saved credentials for the current session.
67
68**Input Schema:**
69
70```json
71{}
72```
73
74**Response (credentials exist):**
75
76```json
77{
78  "username": "player123",
79  "password": "secret456"
80}
81```
82
83**Response (no credentials):**
84
85```
86No credentials saved for this session
87```
88
89## Usage
90
91Register tools with the proxy:
92
93```go
94store, _ := store.Open()
95proxy := mcp.NewProxy(upstream)
96
97proxy.RegisterTool(
98    mcp.NewSaveCredentialsTool(),
99    mcp.MakeSaveCredentialsHandler(store, sessionID),
100)
101
102proxy.RegisterTool(
103    mcp.NewGetCredentialsTool(),
104    mcp.MakeGetCredentialsHandler(store, sessionID),
105)
106```
107
108## Session Isolation
109
110Credentials are strictly scoped:
111
112- Session A saves "user1/pass1" → only Session A can retrieve it
113- Session B saves "user2/pass2" → only Session B can retrieve it
114- Deleting a session automatically removes its credentials
115
116## Testing
117
118All tests pass:
119
120- `internal/mcp/tools_test.go` - Unit tests for tool handlers
121- `internal/mcp/integration_test.go` - Full workflow with proxy
122- `internal/store/credentials_test.go` - Database operations
123- Cascade deletion verified
124- Session isolation verified
125
126## Integration Status
127
128✅ **Tools are registered in the CLI** (`internal/cli/cli.go:145-157`)
129
130The credential tools are automatically registered when the CLI starts:
131
1321. Session is initialized (gets unique sessionID)
1332. Tools are registered with session-scoped handlers
1343. Tools are included in the tool list sent to the LLM
1354. Agent can call `save_credentials` and `get_credentials` automatically
136
137**Logs:**
138- Debug log shows: `Registered local credential tools` with session_id and tool count
139- Info log shows total tool count (upstream + local credentials)
140
141**How it works:**
142
143```go
144// internal/cli/cli.go (lines 145-157)
145proxy.RegisterTool(
146    mcp.NewSaveCredentialsTool(),
147    mcp.MakeSaveCredentialsHandler(db, sessionID),
148)
149proxy.RegisterTool(
150    mcp.NewGetCredentialsTool(),
151    mcp.MakeGetCredentialsHandler(db, sessionID),
152)
153```
154
155The sessionID is injected into the handlers via closure, never exposed to the agent.
156
157## Files Modified
158
1591. `internal/store/store.go` - Added schema + store functions
1602. `internal/mcp/tools.go` - Implemented MCP tools (144 lines)
1613. `internal/mcp/tools_test.go` - Unit tests (213 lines)
1624. `internal/store/credentials_test.go` - Store tests (153 lines)
1635. `internal/cli/cli.go` - Tool registration in CLI
1646. `Makefile` - Added `backup-credentials` command
165
166## Backup and Restore
167
168**Backup credentials:**
169
170```bash
171make backup-credentials
172```
173
174This creates a timestamped SQL file (e.g., `credentials-backup-20260210-180025.sql`) containing INSERT statements for all session credentials.
175
176**Restore credentials:**
177
178```bash
179sqlite3 ~/.config/mysis/mysis.db < credentials-backup-20260210-180025.sql
180```
181
182**Notes:**
183
184- Backup files contain only INSERT statements (no schema)
185- Can be merged into existing database
186- Credentials are tied to session IDs (sessions must exist for foreign key constraint)
187- Backup filename includes timestamp for safe multiple backups