From e0f6aa7533859baa393afdd6be7218ce55b28877 Mon Sep 17 00:00:00 2001
From: Bradley Axen <baxen@squareup.com>
Date: Sat, 14 Dec 2024 17:31:27 -0800
Subject: [PATCH] doc: basic docs and rename types (#471)

---
 crates/mcp-client/src/session.rs              | 2 +-
 crates/mcp-client/src/sse_transport.rs        | 2 +-
 crates/mcp-client/src/stdio_transport.rs      | 2 +-
 crates/mcp-client/src/transport.rs            | 2 +-
 crates/mcp-core/src/content.rs                | 4 +++-
 crates/mcp-core/src/lib.rs                    | 3 +--
 crates/mcp-core/src/{types.rs => protocol.rs} | 1 +
 crates/mcp-core/src/resource.rs               | 1 +
 crates/mcp-core/src/role.rs                   | 1 +
 crates/mcp-core/src/tool.rs                   | 2 ++
 10 files changed, 13 insertions(+), 7 deletions(-)
 rename crates/mcp-core/src/{types.rs => protocol.rs} (98%)

diff --git a/crates/mcp-client/src/session.rs b/crates/mcp-client/src/session.rs
index 7d8a32cb78..1946cea365 100644
--- a/crates/mcp-client/src/session.rs
+++ b/crates/mcp-client/src/session.rs
@@ -1,6 +1,6 @@
 use crate::transport::{ReadStream, WriteStream};
 use anyhow::{anyhow, Context, Result};
-use mcp_core::types::*;
+use mcp_core::protocol::*;
 use serde::de::DeserializeOwned;
 use serde_json::{json, Value};
 use std::sync::atomic::{AtomicU64, Ordering};
diff --git a/crates/mcp-client/src/sse_transport.rs b/crates/mcp-client/src/sse_transport.rs
index dd275486d3..bc5ea88522 100644
--- a/crates/mcp-client/src/sse_transport.rs
+++ b/crates/mcp-client/src/sse_transport.rs
@@ -2,7 +2,7 @@ use crate::transport::{ReadStream, Transport, WriteStream};
 use anyhow::{anyhow, Context, Result};
 use async_trait::async_trait;
 use futures_util::StreamExt;
-use mcp_core::types::JsonRpcMessage;
+use mcp_core::protocol::JsonRpcMessage;
 use reqwest::{Client, Url};
 use reqwest_eventsource::{Event, EventSource};
 use std::sync::Arc;
diff --git a/crates/mcp-client/src/stdio_transport.rs b/crates/mcp-client/src/stdio_transport.rs
index ea95e0e870..67f0fbf120 100644
--- a/crates/mcp-client/src/stdio_transport.rs
+++ b/crates/mcp-client/src/stdio_transport.rs
@@ -1,7 +1,7 @@
 use crate::transport::{ReadStream, Transport, WriteStream};
 use anyhow::{anyhow, Context, Result};
 use async_trait::async_trait;
-use mcp_core::types::*;
+use mcp_core::protocol::*;
 use std::process::Stdio;
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 use tokio::process::{Child, Command};
diff --git a/crates/mcp-client/src/transport.rs b/crates/mcp-client/src/transport.rs
index 77fc2d279c..2ccca05e92 100644
--- a/crates/mcp-client/src/transport.rs
+++ b/crates/mcp-client/src/transport.rs
@@ -1,6 +1,6 @@
 use anyhow::Result;
 use async_trait::async_trait;
-use mcp_core::types::JsonRpcMessage;
+use mcp_core::protocol::JsonRpcMessage;
 use tokio::sync::mpsc::{Receiver, Sender};
 
 // Stream types for consistent interface
diff --git a/crates/mcp-core/src/content.rs b/crates/mcp-core/src/content.rs
index e84696b916..fc1fa9cb1d 100644
--- a/crates/mcp-core/src/content.rs
+++ b/crates/mcp-core/src/content.rs
@@ -1,3 +1,6 @@
+/// Content sent around agents, systems, and LLMs
+/// The various content types can be display to humans but also understood by models
+/// They include optional annotations used to help inform agent usage
 use super::role::Role;
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
@@ -48,7 +51,6 @@ pub struct ImageContent {
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(tag = "type", rename_all = "camelCase")]
-/// Content passed to or from an LLM
 pub enum Content {
     Text(TextContent),
     Image(ImageContent),
diff --git a/crates/mcp-core/src/lib.rs b/crates/mcp-core/src/lib.rs
index b070c0c5fe..ec85712cf5 100644
--- a/crates/mcp-core/src/lib.rs
+++ b/crates/mcp-core/src/lib.rs
@@ -7,5 +7,4 @@ pub mod tool;
 pub use tool::{Tool, ToolCall};
 pub mod resource;
 pub use resource::{Resource, ResourceContents};
-pub mod types;
-pub use types::*;
+pub mod protocol;
diff --git a/crates/mcp-core/src/types.rs b/crates/mcp-core/src/protocol.rs
similarity index 98%
rename from crates/mcp-core/src/types.rs
rename to crates/mcp-core/src/protocol.rs
index dc606ac51d..259050a203 100644
--- a/crates/mcp-core/src/types.rs
+++ b/crates/mcp-core/src/protocol.rs
@@ -1,3 +1,4 @@
+/// The protocol messages exchanged between client and server
 use crate::{content::Content, resource::Resource, resource::ResourceContents, tool::Tool};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
diff --git a/crates/mcp-core/src/resource.rs b/crates/mcp-core/src/resource.rs
index 9972fab0b7..19a44d153f 100644
--- a/crates/mcp-core/src/resource.rs
+++ b/crates/mcp-core/src/resource.rs
@@ -1,3 +1,4 @@
+/// Resources that servers provide to clients
 use anyhow::{anyhow, Result};
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
diff --git a/crates/mcp-core/src/role.rs b/crates/mcp-core/src/role.rs
index 8640f8bdb5..38f3a87239 100644
--- a/crates/mcp-core/src/role.rs
+++ b/crates/mcp-core/src/role.rs
@@ -1,3 +1,4 @@
+/// Roles to describe the origin/ownership of content
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
diff --git a/crates/mcp-core/src/tool.rs b/crates/mcp-core/src/tool.rs
index 81b9b54754..6401b96326 100644
--- a/crates/mcp-core/src/tool.rs
+++ b/crates/mcp-core/src/tool.rs
@@ -1,3 +1,5 @@
+/// Tools represent a routine that a server can execute
+/// Tool calls represent requests from the client to execute one
 use serde::{Deserialize, Serialize};
 use serde_json::Value;