Skip to content

Add architecture diagrams to README documentation#39

Open
jancurn wants to merge 1 commit intomainfrom
claude/add-readme-ascii-diagrams-5D9p5
Open

Add architecture diagrams to README documentation#39
jancurn wants to merge 1 commit intomainfrom
claude/add-readme-ascii-diagrams-5D9p5

Conversation

@jancurn
Copy link
Member

@jancurn jancurn commented Mar 7, 2026

Summary

This PR adds comprehensive ASCII diagrams to the README to visually explain key architectural concepts and workflows in the mcpc tool. These diagrams improve documentation clarity by providing visual representations of complex processes.

Key Changes

  • Session architecture diagram: Illustrates how terminal/script commands communicate with the bridge process and MCP servers via Unix sockets
  • Session lifecycle diagram: Shows the flow of session creation, connection, and termination
  • OAuth 2.1 login flow diagram: Details the authentication process from discovery through token exchange and storage
  • Profiles and sessions relationship diagram: Visualizes how profiles.json, sessions.json, and OS keychain interact
  • MCP proxy setup diagram: Explains how the proxy forwards requests while protecting credentials
  • AI agent tool calling flow diagram: Shows the sequence of tools-list, tools-get, and tools-call operations
  • Payment flow diagram: Illustrates the HTTP 402 payment-required flow with blockchain settlement

Implementation Details

All diagrams are added as code blocks in the README.md file at relevant sections, providing visual context immediately before or after the related text explanations. The diagrams use ASCII art with box-drawing characters for clarity and are formatted consistently throughout the document.

https://claude.ai/code/session_01CLP1rPkK7YsRZTCi8gTzwp

Add visual diagrams explaining:
- Session/bridge architecture (CLI → Unix socket → bridge → MCP server)
- Session lifecycle flow (connect → use → close)
- OAuth 2.1 login flow (browser-based PKCE)
- Profiles and sessions relationship
- MCP proxy setup for AI sandboxing
- AI agent tool calling flow
- x402 agentic payment flow

https://claude.ai/code/session_01CLP1rPkK7YsRZTCi8gTzwp
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants