---
title: server
sidebarTitle: server
---

# `pdsx.mcp.server`


pdsx MCP server implementation using fastmcp.

## Functions

### `_clean_value` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
_clean_value(value: Any) -> dict[str, Any]
```


clean up a record value for semantic density.

removes:
- null fields (embed: null, labels: null, etc.)
- redundant $type fields
- byte indices from facets (keeps just links/mentions)
- verbose reply structure (keeps just uris)


### `_truncate_list_response` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
_truncate_list_response(records: list[RecordResponse], total_fetched: int, has_more: bool) -> list[RecordResponse] | dict[str, Any]
```


truncate list response if it exceeds size limits.

returns either the original list or a dict with truncated results and a message.


### `usage_guide` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
usage_guide() -> str
```


instructions for using pdsx MCP tools.


### `create_post_guide` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_post_guide() -> str
```


instructions for creating posts.


### `list_records` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
list_records(collection: str, limit: int = 10, repo: str | None = None, cursor: str | None = None) -> list[RecordResponse] | dict[str, Any]
```


list records in a collection.

examples:
- list_records("app.bsky.feed.post", repo="zzstoatzz.io") - list someone's posts
- list_records("app.bsky.actor.profile", repo="did:plc:...") - list by DID

**Args:**
- `collection`: the collection to list (e.g., 'app.bsky.feed.post')
- `limit`: max records to return (default 10, max 25)
- `repo`: handle or DID to read from (required)
- `cursor`: pagination cursor from previous response

**Returns:**
- list of records with uri, cid, and value fields


### `get_record` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L312" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_record(uri: str, repo: str | None = None) -> RecordResponse
```


get a specific record by uri.

examples:
- get_record("at://did:plc:.../app.bsky.feed.post/abc123")
- get_record("app.bsky.actor.profile/self", repo="zzstoatzz.io") - someone's profile

**Args:**
- `uri`: full AT-URI or shorthand (collection/rkey)
- `repo`: when using shorthand uri, the repo to read from (required for shorthand)

**Returns:**
- record with uri, cid, and value fields


### `create_record` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_record(collection: str, record: dict[str, Any]) -> CreateResponse
```


create a new record. requires authentication.

**Args:**
- `collection`: the collection to create in (e.g., 'app.bsky.feed.post')
- `record`: the record data. $type and createdAt are auto-added if missing.

**Returns:**
- dict with uri and cid of created record


### `update_record` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L378" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_record(uri: str, updates: dict[str, Any]) -> UpdateResponse
```


update an existing record. requires authentication.

fetches the current record, merges your updates, and puts it back.

**Args:**
- `uri`: full AT-URI or shorthand (collection/rkey)
- `updates`: fields to update (merged with existing record)

**Returns:**
- dict with uri and cid of updated record


### `delete_record` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete_record(uri: str) -> DeleteResponse
```


delete a record. requires authentication.

examples:
- delete_record("app.bsky.feed.post/abc123")
- delete_record("at://did:plc:.../app.bsky.feed.post/abc123")

**Args:**
- `uri`: full AT-URI or shorthand (collection/rkey)

**Returns:**
- confirmation with deleted uri


### `me_resource` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
me_resource() -> str
```


current authenticated user identity.


### `main` <sup><a href="https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/server.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
main() -> None
```


run the MCP server.

