Skip to content

Commit 6cf9524

Browse files
Copilottikazyq
Copilot
and
tikazyq
committed
Add MCP tools and schemas for agent observability (Phase 1 Week 4)
Co-authored-by: tikazyq <[email protected]>
1 parent 4ac6ae5 commit 6cf9524

File tree

4 files changed

+262
-3
lines changed

4 files changed

+262
-3
lines changed

‎packages/mcp/src/schemas/agent-schemas.ts‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
/**
2+
* Agent observability operation schemas
3+
*
4+
* Schemas for AI agent event collection and session management
5+
*/
6+
7+
import { z } from 'zod';
8+
9+
// === BASE SCHEMAS ===
10+
11+
export const ObservabilityAgentTypeSchema = z.enum([
12+
'github-copilot',
13+
'claude-code',
14+
'cursor',
15+
'gemini-cli',
16+
'cline',
17+
'aider',
18+
'mcp-generic',
19+
]).describe('Type of AI coding agent');
20+
21+
export const AgentEventTypeSchema = z.enum([
22+
'session_start',
23+
'session_end',
24+
'file_read',
25+
'file_write',
26+
'file_create',
27+
'file_delete',
28+
'command_execute',
29+
'test_run',
30+
'build_trigger',
31+
'search_performed',
32+
'llm_request',
33+
'llm_response',
34+
'error_encountered',
35+
'rollback_performed',
36+
'commit_created',
37+
'tool_invocation',
38+
'user_interaction',
39+
'context_switch',
40+
]).describe('Type of agent event');
41+
42+
export const EventSeveritySchema = z.enum([
43+
'debug',
44+
'info',
45+
'warning',
46+
'error',
47+
'critical',
48+
]).describe('Severity level of the event');
49+
50+
export const SessionOutcomeSchema = z.enum([
51+
'success',
52+
'partial',
53+
'failure',
54+
'abandoned',
55+
]).describe('Outcome of the agent session');
56+
57+
export const SessionIdSchema = z.string().uuid().describe('Session identifier (UUID)');
58+
59+
export const AgentVersionSchema = z.string().describe('Version of the agent');
60+
61+
// Use numeric project ID for agent observability (database integer)
62+
export const AgentProjectIdSchema = z.number().int().positive().describe('Project identifier');
63+
64+
// === START SESSION ===
65+
66+
export const StartAgentSessionSchema = z.object({
67+
agentId: ObservabilityAgentTypeSchema,
68+
agentVersion: AgentVersionSchema,
69+
projectId: AgentProjectIdSchema,
70+
objective: z.string().optional().describe('What the agent is trying to achieve'),
71+
devlogId: z.number().int().positive().optional().describe('Associated devlog entry ID'),
72+
branch: z.string().describe('Git branch name'),
73+
initialCommit: z.string().describe('Git commit SHA at session start'),
74+
triggeredBy: z.enum(['user', 'automation', 'schedule']).default('user').describe('How the session was triggered'),
75+
});
76+
77+
// === END SESSION ===
78+
79+
export const EndAgentSessionSchema = z.object({
80+
sessionId: SessionIdSchema,
81+
outcome: SessionOutcomeSchema,
82+
qualityScore: z.number().min(0).max(100).optional().describe('Quality score (0-100)'),
83+
finalCommit: z.string().optional().describe('Git commit SHA at session end'),
84+
});
85+
86+
// === LOG EVENT ===
87+
88+
export const LogAgentEventSchema = z.object({
89+
sessionId: SessionIdSchema,
90+
type: AgentEventTypeSchema,
91+
agentId: ObservabilityAgentTypeSchema,
92+
agentVersion: AgentVersionSchema,
93+
projectId: AgentProjectIdSchema,
94+
filePath: z.string().optional().describe('File path if relevant to the event'),
95+
workingDirectory: z.string().describe('Current working directory'),
96+
branch: z.string().optional().describe('Git branch'),
97+
commit: z.string().optional().describe('Git commit SHA'),
98+
devlogId: z.number().int().positive().optional().describe('Associated devlog entry ID'),
99+
data: z.record(z.any()).default({}).describe('Event-specific data (flexible JSON)'),
100+
metrics: z.object({
101+
duration: z.number().optional().describe('Event duration in milliseconds'),
102+
tokenCount: z.number().optional().describe('LLM tokens used'),
103+
fileSize: z.number().optional().describe('File size in bytes'),
104+
linesChanged: z.number().optional().describe('Lines added or removed'),
105+
}).optional().describe('Event metrics'),
106+
parentEventId: z.string().uuid().optional().describe('Parent event ID for causality'),
107+
relatedEventIds: z.array(z.string().uuid()).optional().describe('Related event IDs'),
108+
tags: z.array(z.string()).optional().describe('Searchable tags'),
109+
severity: EventSeveritySchema.optional(),
110+
});
111+
112+
// === QUERY EVENTS ===
113+
114+
export const QueryAgentEventsSchema = z.object({
115+
sessionId: SessionIdSchema.optional(),
116+
projectId: AgentProjectIdSchema.optional(),
117+
agentId: ObservabilityAgentTypeSchema.optional(),
118+
eventType: AgentEventTypeSchema.optional(),
119+
severity: EventSeveritySchema.optional(),
120+
startTime: z.string().datetime().optional().describe('Filter events after this time (ISO 8601)'),
121+
endTime: z.string().datetime().optional().describe('Filter events before this time (ISO 8601)'),
122+
tags: z.array(z.string()).optional().describe('Filter by tags'),
123+
limit: z.number().int().positive().max(1000).default(100).describe('Maximum number of events to return'),
124+
offset: z.number().int().nonnegative().default(0).describe('Number of events to skip'),
125+
});
126+
127+
// === QUERY SESSIONS ===
128+
129+
export const QueryAgentSessionsSchema = z.object({
130+
projectId: AgentProjectIdSchema.optional(),
131+
agentId: ObservabilityAgentTypeSchema.optional(),
132+
outcome: SessionOutcomeSchema.optional(),
133+
startTimeFrom: z.string().datetime().optional().describe('Filter sessions starting after this time (ISO 8601)'),
134+
startTimeTo: z.string().datetime().optional().describe('Filter sessions starting before this time (ISO 8601)'),
135+
minQualityScore: z.number().min(0).max(100).optional().describe('Minimum quality score'),
136+
maxQualityScore: z.number().min(0).max(100).optional().describe('Maximum quality score'),
137+
limit: z.number().int().positive().max(1000).default(100).describe('Maximum number of sessions to return'),
138+
offset: z.number().int().nonnegative().default(0).describe('Number of sessions to skip'),
139+
});
140+
141+
// === GET SESSION ===
142+
143+
export const GetAgentSessionSchema = z.object({
144+
sessionId: SessionIdSchema,
145+
});
146+
147+
// === GET EVENT STATS ===
148+
149+
export const GetEventStatsSchema = z.object({
150+
sessionId: SessionIdSchema.optional(),
151+
projectId: AgentProjectIdSchema.optional(),
152+
startTime: z.string().datetime().optional().describe('Start of time range (ISO 8601)'),
153+
endTime: z.string().datetime().optional().describe('End of time range (ISO 8601)'),
154+
});
155+
156+
// === GET SESSION STATS ===
157+
158+
export const GetSessionStatsSchema = z.object({
159+
projectId: AgentProjectIdSchema.optional(),
160+
startTimeFrom: z.string().datetime().optional().describe('Start of time range (ISO 8601)'),
161+
startTimeTo: z.string().datetime().optional().describe('End of time range (ISO 8601)'),
162+
});
163+
164+
// === GET ACTIVE SESSIONS ===
165+
166+
export const GetActiveSessionsSchema = z.object({
167+
projectId: AgentProjectIdSchema.optional(),
168+
});

‎packages/mcp/src/schemas/index.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,6 @@ export * from './project-schemas.js';
1515

1616
// Document operation schemas
1717
export * from './document-schemas.js';
18+
19+
// Agent observability operation schemas
20+
export * from './agent-schemas.js';

‎packages/mcp/src/tools/agent-tools.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
/**
2+
* Agent observability tools
3+
*
4+
* Tools for AI agent event collection, session management, and analytics
5+
*/
6+
7+
import { Tool } from '@modelcontextprotocol/sdk/types.js';
8+
import { zodToJsonSchema } from '../utils/schema-converter.js';
9+
import {
10+
StartAgentSessionSchema,
11+
EndAgentSessionSchema,
12+
LogAgentEventSchema,
13+
QueryAgentEventsSchema,
14+
QueryAgentSessionsSchema,
15+
GetAgentSessionSchema,
16+
GetEventStatsSchema,
17+
GetSessionStatsSchema,
18+
GetActiveSessionsSchema,
19+
} from '../schemas/index.js';
20+
21+
/**
22+
* Agent observability tools for tracking AI coding agent activities
23+
*
24+
* These tools enable comprehensive monitoring of AI agent behavior including:
25+
* - Session lifecycle tracking (start, end, update)
26+
* - Event collection (file operations, LLM calls, commands, errors)
27+
* - Analytics and statistics
28+
* - Real-time monitoring of active sessions
29+
*/
30+
export const agentTools: Tool[] = [
31+
{
32+
name: 'agent_start_session',
33+
description: 'Start tracking a new AI agent working session. Call this at the beginning of a new task or feature implementation to track all agent activities.',
34+
inputSchema: zodToJsonSchema(StartAgentSessionSchema),
35+
},
36+
37+
{
38+
name: 'agent_end_session',
39+
description: 'End an AI agent session and record the outcome. Call this when completing or abandoning a task.',
40+
inputSchema: zodToJsonSchema(EndAgentSessionSchema),
41+
},
42+
43+
{
44+
name: 'agent_log_event',
45+
description: 'Log a specific AI agent event (file operation, LLM call, command execution, error, etc.). Use this to record individual actions during a session.',
46+
inputSchema: zodToJsonSchema(LogAgentEventSchema),
47+
},
48+
49+
{
50+
name: 'agent_query_events',
51+
description: 'Query and filter agent events with various criteria. Use this to analyze agent behavior, debug issues, or generate reports.',
52+
inputSchema: zodToJsonSchema(QueryAgentEventsSchema),
53+
},
54+
55+
{
56+
name: 'agent_query_sessions',
57+
description: 'Query and filter agent sessions with various criteria. Use this to review past work, compare outcomes, or analyze patterns.',
58+
inputSchema: zodToJsonSchema(QueryAgentSessionsSchema),
59+
},
60+
61+
{
62+
name: 'agent_get_session',
63+
description: 'Get detailed information about a specific agent session including all metrics and context.',
64+
inputSchema: zodToJsonSchema(GetAgentSessionSchema),
65+
},
66+
67+
{
68+
name: 'agent_get_event_stats',
69+
description: 'Get aggregated statistics about agent events (counts by type, severity, token usage, etc.). Useful for performance analysis.',
70+
inputSchema: zodToJsonSchema(GetEventStatsSchema),
71+
},
72+
73+
{
74+
name: 'agent_get_session_stats',
75+
description: 'Get aggregated statistics about agent sessions (success rates, quality scores, duration, etc.). Useful for productivity analysis.',
76+
inputSchema: zodToJsonSchema(GetSessionStatsSchema),
77+
},
78+
79+
{
80+
name: 'agent_get_active_sessions',
81+
description: 'Get all currently active (ongoing) agent sessions. Use this for real-time monitoring.',
82+
inputSchema: zodToJsonSchema(GetActiveSessionsSchema),
83+
},
84+
];

‎packages/mcp/src/tools/index.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,27 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
22
import { devlogTools } from './devlog-tools.js';
33
import { projectTools } from './project-tools.js';
44
import { documentTools } from './document-tools.js';
5+
import { agentTools } from './agent-tools.js';
56

67
/**
78
* All available MCP tools - devlog-specific naming
89
*
910
* See server description for complete terminology and context.
1011
*
11-
* Total: 15 tools
12+
* Total: 24 tools
1213
* - 7 devlog tools: create_devlog, get_devlog, update_devlog, list_devlogs,
1314
* add_devlog_note, complete_devlog, find_related_devlogs
1415
* - 3 project tools: list_projects, get_current_project, switch_project
1516
* - 5 document tools: upload_devlog_document, list_devlog_documents,
1617
* get_devlog_document, delete_devlog_document, search_devlog_documents
18+
* - 9 agent tools: agent_start_session, agent_end_session, agent_log_event,
19+
* agent_query_events, agent_query_sessions, agent_get_session,
20+
* agent_get_event_stats, agent_get_session_stats, agent_get_active_sessions
1721
*/
18-
export const allTools: Tool[] = [...devlogTools, ...projectTools, ...documentTools];
22+
export const allTools: Tool[] = [...devlogTools, ...projectTools, ...documentTools, ...agentTools];
1923

2024
// Re-export tool groups
21-
export { devlogTools, projectTools, documentTools };
25+
export { devlogTools, projectTools, documentTools, agentTools };
2226

2327
// Simplified tool categories
2428
export const coreTools = devlogTools.filter((tool) =>

0 commit comments

Comments
 (0)