Skip to content

Commit a09c0ac

Browse files
cairijuncairijun
authored
feat: add MCP client (#2549)
1 parent c86466e commit a09c0ac

File tree

27 files changed

+3216
-322
lines changed

27 files changed

+3216
-322
lines changed

‎doc/.vitepress/config.mjs‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,14 @@ export default withMermaid(
119119
{ text: "Installation", link: "/installation" },
120120
{ text: "Getting Started", link: "/getting-started" },
121121
{ text: "Upgrading", link: "/upgrading" },
122+
{
123+
text: "Agent Client Protocol (ACP)",
124+
link: "agent-client-protocol",
125+
},
126+
{
127+
text: "Model Context Protocol (MCP)",
128+
link: "model-context-protocol",
129+
},
122130
{
123131
text: "Configuration",
124132
collapsed: true,
@@ -132,6 +140,7 @@ export default withMermaid(
132140
text: "Inline Assistant",
133141
link: "/configuration/inline-assistant",
134142
},
143+
{ text: "MCP", link: "/configuration/mcp" },
135144
{ text: "Prompt Library", link: "/configuration/prompt-library" },
136145
{ text: "Rules", link: "/configuration/rules" },
137146
{ text: "System Prompt", link: "/configuration/system-prompt" },
@@ -143,7 +152,6 @@ export default withMermaid(
143152
collapsed: false,
144153
items: [
145154
{ text: "Introduction", link: "/usage/introduction" },
146-
{ text: "ACP Protocol", link: "/usage/acp-protocol" },
147155
{ text: "Action Palette", link: "/usage/action-palette" },
148156
{
149157
text: "Chat Buffer",
@@ -162,6 +170,8 @@ export default withMermaid(
162170
},
163171
{ text: "Events", link: "/usage/events" },
164172
{ text: "Inline Assistant", link: "/usage/inline-assistant" },
173+
{ text: "MCP", link: "/usage/mcp" },
174+
{ text: "Action Palette", link: "/usage/action-palette" },
165175
{ text: "Prompt Library", link: "/usage/prompt-library" },
166176
{ text: "Workflows", link: "/usage/workflows" },
167177
{ text: "UI", link: "/usage/ui" },

doc/usage/acp-protocol.md renamed to doc/agent-client-protocol.md

Lines changed: 20 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,28 @@
22
description: How CodeCompanion implements the Agent Client Protocol (ACP)
33
---
44

5-
# ACP Protocol Reference
5+
# Agent Client Protocol (ACP) Support
66

77
CodeCompanion implements the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) to enable you to work with coding agents from within Neovim. ACP is an open standard that enables structured interaction between clients (like CodeCompanion) and AI agents, providing capabilities such as session management, file system operations, tool execution, and permission handling.
88

99
This page provides a technical reference for what's supported in CodeCompanion and how it's been implemented.
1010

11-
## Protocol Support
11+
## Implementation
1212

1313
CodeCompanion provides comprehensive support for the ACP specification:
1414

15-
| Feature Category | Support Level | Details |
15+
| Feature Category | Supported | Details |
1616
|------------------|---------------|---------|
17-
| **Core Protocol** | ✅ Full | JSON-RPC 2.0, streaming responses, message buffering |
18-
| **Session Management** | ✅ Full | Create, load, and persist sessions with state tracking |
19-
| **Authentication** | ✅ Full | Multiple auth methods, adapter-level hooks |
20-
| **File System** | ✅ Full | Read/write text files with line ranges |
21-
| **Permissions** | ✅ Full | Interactive UI with diff preview for tool approval |
22-
| **Content Types** | ✅ Full | Text, images, embedded resources |
23-
| **Tool Calls** | ✅ Full | Content blocks, file diffs, status updates |
24-
| **Session Modes** | ✅ Full | Mode switching and state management |
25-
| **MCP Integration** | ✅ Full | Stdio, HTTP, and SSE transports |
17+
| **Core Protocol** | ✅ | JSON-RPC 2.0, streaming responses, message buffering |
18+
| **Authentication** | ✅ | Multiple auth methods, adapter-level hooks |
19+
| **Content Types** | ✅ | Text, images, embedded resources |
20+
| **File System** | ✅ | Read/write text files with line ranges |
21+
| **MCP Integration** | ✅ | Stdio, HTTP, and SSE transports |
22+
| **Permissions** | ✅ | Interactive UI with diff preview for tool approval |
23+
| **Session Management** | ✅ | Create, load, and persist sessions with state tracking |
24+
| **Session Modes** | ✅ | Mode switching |
25+
| **Session Models** | ✅ | Select specific models |
26+
| **Tool Calls** | ✅ | Content blocks, file diffs, status updates |
2627
| **Agent Plans** | ❌ | Visual display of an agent's execution plan |
2728
| **Terminal Operations** | ❌ | Terminal capabilities not implemented |
2829

@@ -45,42 +46,22 @@ CodeCompanion advertises the following capabilities to ACP agents:
4546
}
4647
```
4748

48-
### Content Support
49+
### Content Types
4950

5051

5152
| Content Type | Send to Agent | Receive from Agent |
5253
|--------------|---------------|-------------------|
5354
| Text | ✅ | ✅ |
54-
| Images | ✅ | ✅ |
55-
| Embedded Resources | ✅ | ✅ |
56-
| Audio | ❌ | ❌ |
5755
| File Diffs | N/A | ✅ |
56+
| Images | ✅ | ❌ |
57+
| Audio | ❌ | ❌ |
58+
| Embedded Resources | ❌ | ❌ |
5859

5960

60-
### Session Updates Handled
61-
62-
CodeCompanion processes the following session update types:
63-
64-
- **Message chunks**: Streamed text from agent responses
65-
- **Thought chunks**: Agent reasoning displayed separately
66-
- **Tool calls**: Full execution lifecycle with status tracking
67-
- **Mode changes**: Automatic UI updates when modes switch
68-
- **Available commands**: Dynamic command registration for completion
69-
70-
## Implementation Notes
71-
72-
### Message Buffering
73-
74-
JSON-RPC message boundaries don't always align with I/O boundaries. CodeCompanion buffers stdout from the agent process and extracts complete JSON-RPC messages line-by-line, ensuring robust parsing even with partial reads.
75-
7661
### State Management
7762

7863
Unlike HTTP adapters which are stateless (sending the full conversation history with each request), ACP adapters are stateful. The agent maintains the conversation context, so CodeCompanion only sends new messages with each prompt. Session IDs are tracked throughout the conversation lifecycle.
7964

80-
### Tool Call Caching
81-
82-
Tool call state is maintained in memory to support permission requests. When an agent requests permission for a tool call, the cached details enable features like the diff preview UI for file edits.
83-
8465
### File Context Handling
8566

8667
When sending files as embedded resources to agents, CodeCompanion re-reads the file content rather than using the chat buffer representation. This avoids HTTP-style `<attachment>` tags that are used for LLM adapters but don't make sense for ACP agents.
@@ -93,41 +74,27 @@ ACP agents can advertise their own slash commands dynamically. You can access th
9374

9475
CodeCompanion implements a `session/set_model` method that allows you to select a model for the current session. This feature is not part of the [official ACP specification](https://agentclientprotocol.com/protocol/draft/schema#session-set_model) and is subject to change in future versions.
9576

96-
### Graceful Degradation
97-
98-
CodeCompanion checks an agent's capabilities during initialization and gracefully falls back to supported content types. For example, if an agent doesn't support embedded context, files are sent as plain text instead.
99-
10077
### Cleanup and Lifecycle
10178

10279
CodeCompanion ensures clean disconnection from ACP agents by hooking into Neovim's `VimLeavePre` autocmd. This guarantees that agent processes are properly terminated even if Neovim exits unexpectedly.
10380

104-
## Key Features
105-
106-
- **Streaming**: Real-time response streaming with chunk-by-chunk rendering
107-
- **Permission System**: Interactive approval for file operations with diff preview
108-
- **Session Persistence**: Resume previous conversations across Neovim sessions
109-
- **Mode Management**: Switch between agent modes (e.g. ask, architect, code)
110-
- **MCP Servers**: Connect agents to external tools via the Model Context Protocol
111-
- **Slash Command Completion**: Auto-complete agent-specific commands with `\command` syntax
112-
- **Error Handling**: Comprehensive error messages and graceful degradation
113-
11481
## Protocol Version
11582

11683
CodeCompanion currently implements **ACP Protocol Version 1**.
11784

11885
The protocol version is negotiated during initialization. If an agent selects a different version, CodeCompanion will log a warning but continue to operate, following the agent's selected version.
11986

120-
## Known Limitations
87+
## Current Limitations
12188

12289
- **Terminal Operations**: The `terminal/*` family of methods (`terminal/create`, `terminal/output`, `terminal/release`, etc.) are not implemented. CodeCompanion doesn't advertise terminal capabilities to agents.
12390

12491
- **Agent Plan Rendering**: [Plan](https://agentclientprotocol.com/protocol/agent-plan) updates from agents are received and logged, but they're not currently rendered in the chat buffer UI.
12592

126-
- **Audio Content**: Audio content blocks aren't sent in prompts, despite capability detection.
93+
- **Audio Content**: Audio can't be sent or received
12794

12895
## See Also
12996

97+
- [Agent Client Protocol Specification](https://agentclientprotocol.com/) - Official ACP documentation
13098
- [Configuring ACP Adapters](/configuration/adapters-acp) - Setup instructions for specific agents
13199
- [Using Agents](/usage/chat-buffer/agents) - How to interact with agents in chat
132-
- [Agent Client Protocol Specification](https://agentclientprotocol.com/) - Official ACP documentation
133100

0 commit comments

Comments
 (0)